Simple Network Management Protocol

SNMP Start Page

SNMP Service

Purpose

The Microsoft® Windows® 2000 implementation of the Simple Network Management Protocol (SNMP) is a service that supports computers running TCP/IP and IPX protocols. You can use SNMP to configure remote devices, monitor network performance, audit network usage, and detect network faults or inappropriate access.

Where Applicable

SNMP uses a distributed architecture consisting of management applications and agent applications. The SNMP service implements an SNMP agent. To use the information the SNMP service provides, you must have at least one host that is running an SNMP management application. You can use third-party SNMP management software, or you can develop your own SNMP management software application. Windows 2000 provides the following APIs for this purpose:

  • SNMP Management API, a set of functions that can be used to quickly develop basic SNMP management systems

  • WinSNMP API, version 2.0, a set of functions for encoding, decoding, sending, and receiving SNMP messages in the Windows 2000 operating environment

Additionally, the SNMP Extension Agent API defines the interface between the SNMP service and third-party SNMP extension agent DLLs. The SNMP Utility API functions can be used to simplify the processing of SNMP messages.

Developer Audience

The APIs listed in the preceding section are designed for use by C/C++ programmers. Familiarity with SNMP and SNMPv2C, as well as a working knowledge of networking and network management concepts, are required.

Run-time Requirements

Requires Windows NT® or Windows® 2000; the Microsoft SNMP extension agent also runs on Windows 95 and Windows 98, and Microsoft® Windows® Millennium Edition clients. For information about the operating system required to use a particular function, see the Requirements section of the reference page for that function. Applications that use the WinSNMP API require Windows 2000.

See Also

Dynamic Host Configuration Protocol (DHCP)

Network Management

Remote Access Service

Routing and Remote Access Service

Overviews

General information about SNMP and the WinSNMP API.

Reference

Documentation for the following:

Microsoft's SNMP Extension Agent, Management, and Utility APIs

WinSNMP API

Feedback

Make error reports and feature requests directly to Microsoft.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Simple Network Management Protocol (SNMP)

The Simple Network Management Protocol (SNMP) is the Internet standard protocol for exchanging management information between management console applications such as HP Openview, Novell NMS, IBM NetView, or Sun Net Manager, and managed entities. The managed entities can include hosts, routers, bridges, and hubs.


About SNMP

SNMP uses a distributed architecture consisting of managers and agents. An agent is an SNMP application that responds to queries from SNMP manager applications. The SNMP agent is responsible for retrieving and updating local management information based on the requests of the SNMP manager. The agent also notifies registered managers when significant events or traps occur. A manager is an SNMP application that generates queries to SNMP agent applications and receives traps from SNMP agent applications.

On computers running Microsoft® Windows NT®/Windows® 2000 the SNMP agent is implemented by the SNMP service (SNMP.EXE). The SNMP manager is typically a third-party SNMP management console application. The management console application does not need to run on the same host as the SNMP agent. To use the information the Microsoft SNMP service provides, you need at least one SNMP management console application. The system includes libraries that support SNMP management console applications, but it does not include an SNMP management console application at this time.


How SNMP Works

The following steps outline how a third-party SNMP management console application returns information from the SNMP service:

  1. The SNMP management console application formulates an SNMP message based on input from the user. The message includes a protocol data unit (PDU) and authentication information. The management console application can use the Microsoft SNMP Management API library (MGMTAPI.DLL) or the Microsoft WinSNMP API library (WSNMP32.DLL) to perform this step.
  2. The SNMP management console application sends the SNMP message to the SNMP service, using the SNMP service libraries.
  3. The SNMP service receives the request. It verifies the authentication information and the source IP address.
  4. The SNMP service selects the appropriate extension agent and requests that the agent retrieve the requested information.
  5. The SNMP service sends the response to the SNMP management console application.


The SNMP Management Information Base (MIB)

A Management Information Base (MIB) describes a set of managed objects. An SNMP management console application can manipulate the objects on a specific computer if the SNMP service has an extension agent DLL that supports the MIB.

Each managed object in a MIB has a unique identifier. The identifier includes the object's type (such as counter, string, gauge, or address), the object's access level (such as read or read/write), size restrictions, and range information.

Windows NT: Typically, you can copy a MIB from the SNMP extension agent that supports the particular MIB. Some additional MIBs are available with the Windows NT 4.0 Resource Kit.

Windows 2000 or later: The following table contains a partial list of the MIBs that ship with Windows 2000. They are installed with the SNMP service in the %systemroot%\system32 directory. For a complete listing of MIBs, refer to the Windows 2000 Resource Kit.

MIB | Description
DHCP.MIB | Microsoft-defined MIB that contains object types for monitoring the network traffic between remote hosts and DHCP servers
HOSTMIB.MIB | Contains object types for monitoring and managing host resources
LMMIB2.MIB | Covers workstation and server services
MIB_II.MIB | Contains the Management Information Base (MIB-II), which provides a simple, workable architecture and system for managing TCP/IP-based internets
WINS.MIB | Microsoft-defined MIB for the Windows Internet Name Service (WINS)

The extension agent DLLs for MIB-II, LAN Manager MIB-II, and the Host Resources MIB are installed with the SNMP service. The extension agent DLLs for the other MIBs are installed when their respective services are installed. At service startup time, the SNMP service loads all of the extension agent DLLs that are listed in the registry.

Users can add other extension agent DLLs that implement additional MIBs. To do this, they must add a registry entry for the new DLL under the SNMP service. They must also register the new MIB with the SNMP management console application. For more information, see the documentation included with your management console application.


MIB Name Tree

The name space for MIB object identifiers is hierarchical. It is structured so that each manageable object can be assigned a globally unique name.

Authority for parts of the name space is assigned to individual organizations. This allows organizations to assign names without consulting an Internet authority for each assignment. For example, the name space assigned to Microsoft is 1.3.6.1.4.1.311, which is defined in MSFT.MIB. Microsoft has the authority to assign names to objects anywhere below that name space.

The object identifier in the hierarchy is written as a sequence of subidentifiers beginning at the root and ending at the object. Subidentifiers are separated with a period.


Relevant RFCs

TCP/IP standards are defined in Requests for Comments (RFCs), which are published by the Internet Engineering Task Force (IETF). The following table lists the RFCs that are relevant to SNMP.

RFC number | Title
1155 | "Structure and Identification of Management Information for TCP/IP-based Internets." It defines SMI.MIB.
1157 | "A Simple Network Management Protocol (SNMP)." It defines SNMP itself.
1213 | "Management Information Base for Network Management of TCP/IP-based internets: MIB-II." It defines MIB_II.MIB.
1901 | "Introduction to Community-based SNMPv2"
1902 | "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1903 | "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1904 | "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1905 | "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1906 | "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1907 | "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1908 | "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework"
2089 | "V2ToV1 Mapping SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent"


System Files for SNMP

The following table describes the principal files that relate to the SNMP service.

Filename | Description
DHCPMIB.DLL | Extension agent DLL that implements the Microsoft-defined DHCP MIB. Installed only on DHCP servers, and not available on Windows NT 3.1.
EVNTAGNT.DLL | SNMP DLL that translates event logs into SNMP traps; also known as the SNMP event translator.
HOSTMIB.DLL | Extension agent DLL that implements the Host Resources MIB.
LMMIB2.DLL | Extension agent DLL that implements LAN Manager MIB-II.
MGMTAPI.DLL | Microsoft Windows 2000-based SNMP Management API library. This API allows SNMP manager applications to "listen" for SNMP manager requests, and send requests to and receive responses from SNMP agents.
MIB.BIN | Compiled MIB information used by MGMTAPI.DLL.
SNMP.EXE | SNMP service. This is the master agent that receives SNMP requests and delivers them to the appropriate extension agent DLL.
SNMPAPI.DLL | SNMP utilities DLL used by SNMP extension agent DLLs and manager applications. This DLL contains a framework for developing extension agent DLLs.
SNMPSNAP.DLL | SNMP configuration application that is a Microsoft Management Console (MMC) snap-in component. The snap-in adds several pages to the SNMP Service Properties sheet. For more information, see the online help for the SNMP service.
SNMPTRAP.EXE | SNMP trap service. Receives SNMP traps and forwards them to SNMP manager applications.
WINSMIB.DLL | Extension agent DLL that implements the Microsoft-defined WINS MIB. Installed only on WINS servers, and not available on Windows NT 3.1.
WSNMP32.DLL | Microsoft Windows 2000-based WinSNMP API library. This API allows SNMP manager applications to "listen" for SNMP manager requests, and send requests to and receive responses from SNMP agents.

For additional information, see The SNMP Management Information Base (MIB). (You can also refer to the Windows NT/Windows 2000 Resource Kit.)


SNMP Utilities

The following table lists the SNMP utilities that are available in the Microsoft Windows Resource Kit.

Filename | Description
EVNTCMD.EXE | A command-line application for configuring the SNMP event translator
EVNTWIN.EXE | An application that provides a user interface for configuring the SNMP event translator
MIBCC.EXE | The SNMP MIB Compiler
SNMPUTIL.EXE | A sample SNMP manager console application


Configuring the SNMP Service

On occasion, you may need to reconfigure SNMP. In these instances, you need to know community names in your network, the trap destination for each community, and IP addresses or computer names for SNMP management hosts before you use or reconfigure SNMP services. For more information, refer to the Windows NT/Windows 2000 Resource Kit and to the SNMP service online documentation.

The following topics contain information relevant to configuring the SNMP service:

  • Community names
  • Host names and IP addresses
  • Configuring SNMP security
  • Configuring SNMP agent information

If you use the Microsoft Management Console (MMC) snap-in for Group Policy to administer registry-based policy settings that apply to SNMP, one or more of the following subkeys may exist. The SNMP MMC snap-in permits users to view these parameters, but users cannot change the settings on Whistler or later.

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\SNMP\
Parameters\ValidCommunities

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\SNMP\
Parameters\PermittedManagers

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\SNMP\
Parameters\TrapConfiguration

For more information about registry-based policy settings, see About Group Policy.

Typically, only members of the Administrators local group can access the following registry subkeys that store configuration data for the SNMP service:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
SNMP\Parameters\ValidCommunities

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
SNMP\Parameters\PermittedManagers


Community Names

A community name identifies a collection of SNMP managers and agents. The use of a community name provides primitive security and context checking for both agents and managers that receive requests and initiate trap operations. An agent won't accept a request from a manager outside the community.


Host Names and IP Addresses

If the computer does not have access to a WINS server, the SNMP service uses the HOSTS file to resolve host names to IP addresses. The HOST file is merely a text file listing explicit host names and IP addresses. If you use host names, be sure to add all host name and IP address mappings of the participating systems.


Configuring SNMP Security

SNMP security allows you to specify the communities and hosts from which a computer accepts requests, as well as the type of operations to accept from the computers belonging to a community. The security also allows you to specify whether to send an authentication trap when an unauthorized community or host requests information.


Configuring SNMP Agent Information

SNMP agent information allows you to specify comments about the user and the physical location of the computer and to indicate the types of service to report. The types of service that can be reported are based on the computer's configuration.


SNMP Reference

The following sections describe in detail the SNMP functions and structures. These elements support the development of SNMP agent applications and SNMP manager applications for Windows NT®/Windows® 2000.

  • SNMP Functions
  • SNMP Structures
  • SNMP Variable Types and Request PDU Types


SNMP Functions

The SNMP functions fall into the following three functional groupings:

  • SNMP Extension Agent API functions
  • SNMP Management API functions
  • SNMP Utility API functions

SNMP Extension Agent API Functions

The SNMP Extension Agent API functions define the interface between the SNMP service and the third-party SNMP extension agent DLLs. Applications use these functions to resolve the variable bindings specified by incoming SNMP PDUs.

SnmpExtensionClose
SnmpExtensionInit
SnmpExtensionInitEx
SnmpExtensionMonitor
SnmpExtensionQuery
SnmpExtensionQueryEx
SnmpExtensionTrap

SNMP Management API Functions

The SNMP Management API functions define the interface between third-party SNMP manager applications and the management function dynamic-link library MGMTAPI.DLL. The DLL works in conjunction with the SNMP trap service (SNMPTRAP.EXE), and can interact with one or more third-party SNMP manager applications. Third-party manager applications can use the management functions to perform SNMP manager operations.

SnmpMgrClose
SnmpMgrCtl
SnmpMgrGetTrap
SnmpMgrGetTrapEx
SnmpMgrOidToStr
SnmpMgrOpen
SnmpMgrRequest
SnmpMgrStrToOid
SnmpMgrTrapListen

SNMP Utility API Functions

The SNMP Utility API functions simplify manipulation of SNMP data structures and provide functionality that is useful during the development of SNMP applications.

SnmpSvcGetUptime
SnmpSvcSetLogLevel
SnmpSvcSetLogType
SnmpUtilAsnAnyCpy
SnmpUtilAsnAnyFree
SnmpUtilDbgPrint SnmpUtilIdsToA
SnmpUtilMemAlloc
SnmpUtilMemFree
SnmpUtilMemReAlloc
SnmpUtilOctetsCmp
SnmpUtilOctetsCpy
SnmpUtilOctetsFree
SnmpUtilOctetsNCmp
SnmpUtilOidAppend
SnmpUtilOidCmp
SnmpUtilOidCpy
SnmpUtilOidFree
SnmpUtilOidNCmp SnmpUtilOidToA
SnmpUtilPrintAsnAny
SnmpUtilPrintOid
SnmpUtilVarBindCpy
SnmpUtilVarBindListCpy
SnmpUtilVarBindFree
SnmpUtilVarBindListFree


SnmpExtensionClose

The Microsoft SNMP service calls the SnmpExtensionClose function to request that the SNMP extension agent deallocate resources and terminate operations. This function is an element of the SNMP Extension Agent API.

Note The SNMP service calls the SnmpExtensionClose function only if the extension agent is running on Windows 2000. For more information, see the following Remarks section.

VOID SnmpExtensionClose();

Parameters

This function has no parameters.

Remarks

On Windows 2000 and later, it is not necessary for the extension agent to call its own SnmpExtensionClose entry point. This is because the SNMP service calls the extension agent's SnmpExtensionClose function when the service unloads the extension agent from the service's address space. The extension agent can clean up allocated resources and terminate services at this time.

An SNMP extension agent that runs on Windows NT 4.0 can also export the SnmpExtensionClose function. However, in this case the SNMP service does not call the function. The extension agent must call SnmpExtensionClose and perform cleanup when the SNMP service calls the extension agent's DllMain entry-point function with the value DLL_PROCESS_DETACH.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionInitEx


SnmpExtensionInit

The Microsoft SNMP service calls the SnmpExtensionInit function to initialize the SNMP extension agent DLL. This function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionInit(
  DWORD dwUptimeReference,                    // see NOTE below
  HANDLE *phSubagentTrapEvent,                // trap event handle
  AsnObjectIdentifier *pFirstSupportedRegion  // first MIB subtree
);

Parameters

dwUptimeReference
[in] Specifies a time-zero reference for the extension agent.

Note Extension agents should ignore this parameter. The SNMP extension agent DLL should use the SnmpSvcGetUptime function to retrieve the number of centiseconds the SNMP service has been running. For more information, see the following Remarks section.

phSubagentTrapEvent
[out] Pointer to an event handle the extension agent passes back to the SNMP service. This handle is used to notify the service that the extension agent has one or more traps to send. For additional information about allocating and deallocating the event handle, see the following Remarks section.
pFirstSupportedRegion
[out] Pointer to an AsnObjectIdentifier structure to receive the first MIB subtree that the extension agent supports. For additional information about allocating and deallocating resources for this structure, see the following Remarks section.

The extension agent can register additional MIB subtrees by implementing the SnmpExtensionInitEx entry point function.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Extension agents should ignore the dwUptimeReference parameter. Instead, they should call the SnmpSvcGetUptime function to retrieve the number of centiseconds that the Microsoft SNMP service has been running. Because the dwUptimeReference parameter stores the elapsed time as a DWORD value in milliseconds, the time can wrap to zero and reflect an inaccurate time interval.

The extension agent notifies the SNMP service that it needs to send one or more traps by setting the event handle passed back in the phSubagentTrapEvent parameter to the signaled state. After this event has been signaled, the SNMP service repeatedly calls the extension agent's SnmpExtensionTrap entry point until the function returns a value of FALSE. This indicates that the extension agent has no more traps to send. If the extension agent does not generate traps, the phSubagentTrapEvent parameter should return a value of NULL.

The SNMP extension agent must allocate and deallocate resources for the trap event handle. When the SNMP service calls the SnmpExtensionInit function, the extension agent must call the CreateEvent function to allocate the event handle. The extension agent passes the handle to the SNMP service in the phSubagentTrapEvent parameter. When the SNMP service calls the SnmpExtensionClose function, the extension agent must deallocate resources for the trap event handle.

The SNMP service makes a copy of the AsnObjectIdentifier structure the extension agent returns in the pFirstSupportedRegion parameter. The extension agent must allocate and deallocate the resources associated with the original structure. It can do this when the SNMP service calls the SnmpExtensionClose function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnObjectIdentifier, CreateEvent, SnmpExtensionTrap, SnmpSvcGetUptime, SnmpExtensionClose, SnmpExtensionMonitor


SnmpExtensionInitEx

The Microsoft SNMP service calls the SnmpExtensionInitEx function to identify any additional management information base (MIB) subtrees the SNMP extension agent supports. This function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionInitEx(
  AsnObjectIdentifier *pNextSupportedRegion  // next MIB subtree
);

Parameters

pNextSupportedRegion
[out] Pointer to an AsnObjectIdentifier structure to receive the next MIB subtree that the extension agent supports.

Return Values

If the pNextSupportedRegion parameter has been initialized with an additional MIB subtree, the return value is TRUE.

If there are no more MIB subtrees to register, the return value is FALSE.

Remarks

The SNMP service repeatedly calls the SnmpExtensionInitEx function entry point so the extension agent can register support for additional MIB subtrees.

The SNMP service makes a copy of the AsnObjectIdentifier structure the extension agent returns in the pNextSupportedRegion parameter. The extension agent must allocate and deallocate the resources associated with the original structure. It can do this when the SNMP service calls the SnmpExtensionClose function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionClose, AsnObjectIdentifier, SnmpExtensionMonitor


SnmpExtensionMonitor

The Microsoft SNMP service calls the SnmpExtensionMonitor function to provide the SNMP extension agent with a view to the service's internal counters and parameters. This function is an element of the SNMP Extension Agent API.

The SnmpExtensionMonitor function is optional. Extension agents should implement the function if they are interested in a view of the SNMP service's internal management objects, as defined in RFC 1213, "Management Information Base for Network Management of TCP/IP-based internets: MIB-II."

BOOL SnmpExtensionMonitor(
  LPVOID pAgentMgmtData
);

Parameters

pAgentMgmtData
[in] Pointer to an array of AsnAny objects (structures). The number of objects, and the type and description of each object, are in accordance with RFC 1213. For more information, see the following Remarks section.

Return Values

Unless an unexpected error occurs while the SNMP extension agent is processing the value of the pAgentMgmtData parameter, the extension agent should return TRUE. If the extension agent returns FALSE, the SNMP service does not load the extension agent, and the service stops directing SNMP requests to the extension agent.

Remarks

If the extension agent exports the SnmpExtensionMonitor function, the SNMP service calls the function during initialization of the extension agent, immediately after the service calls the SnmpExtensionInit and the SnmpExtensionInitEx functions.

The SNMP service dynamically updates the SNMP counters (for example, the snmpInPkts and the snmpOutNoSuchNames counters) in the array pointed to by the pAgentMgmtData parameter. In order to be able to read these values while the SNMP service is running, the extension agent must store the pointer to pAgentMgmtData.

Note that an SNMP extension agent should not update the memory pointed to by the pAgentMgmtData parameter. This is because the values of the SNMP service's internal counters would no longer be valid, and the behavior of the SNMP service could become unpredictable. As long as the extension agent does not alter it, the memory pointed to by pAgentMgmtData is valid while the SNMP service is running.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionInitEx, SnmpExtensionClose, AsnAny


SnmpExtensionQuery

The Microsoft SNMP service calls the SnmpExtensionQuery function to resolve SNMP requests that contain variables within one or more of the SNMP extension agent's registered MIB subtrees. This function is an element of the SNMP Extension Agent API.

Note The extension agent must export the SnmpExtensionQuery function if the extension agent runs on Windows NT 3.51 or 4.0. However, it is recommended that you use the SnmpExtensionQueryEx function, which supports SNMP version 2C (SNMPv2C) data types and multiphase SNMP SET operations.

BOOL SnmpExtensionQuery(
  BYTE bPduType,                  // SNMPv1 PDU request type
  SnmpVarBindList *pVarBindList,  // pointer to variable bindings
  AsnInteger32 *pErrorStatus,     // pointer to SNMPv1 error status
  AsnInteger32 *pErrorIndex       // pointer to the error index
);

Parameters

bPduType
[in] Specifies the SNMP version 1 (SNMPv1) PDU request type. This parameter can be one of the following values.
Value | Meaning
SNMP_PDU_GET | Retrieve the value or values of the specified variables.
SNMP_PDU_GETNEXT | Retrieve the value or values of the lexicographic successor of the specified variable.
SNMP_PDU_SET | Write a value within a specific variable.

Note that PDU request types have been renamed. For additional information, see SNMP Variable Types and Request PDU Types.

pVarBindList
[in/out] Pointer to the variable bindings list.
pErrorStatus
[out] Pointer to a variable in which the error status result will be returned. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_ERRORSTATUS_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERRORSTATUS_TOOBIG | The agent could not place the results of the requested operation into a single SNMP message.
SNMP_ERRORSTATUS_NOSUCHNAME | The requested operation identified an unknown variable.
SNMP_ERRORSTATUS_BADVALUE | The requested operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERRORSTATUS_READONLY | The requested operation tried to change a variable that was not allowed to change according to the community profile of the variable.
SNMP_ERRORSTATUS_GENERR | An error other than one of those listed here occurred during the requested operation.

pErrorIndex
[out] Pointer to a variable in which the error index result will be returned.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When the SNMP service receives an SNMP PDU request, it calls the SnmpExtensionQuery function to process the request. The extension agent must follow the rules in RFC 1157 to either resolve the variable bindings or generate an error.

If the extension agent cannot resolve the variable bindings on a Get Next request, it must change the name field of the SnmpVarBind structure to the value of the object identifier immediately following that of the currently supported MIB subtree view. For example, if the extension agent supports view ".1.3.6.1.4.1.77.1", a Get Next request on ".1.3.6.1.4.1.77.1.5.1" would result in a modified name field of ".1.3.6.1.4.1.77.2". This signals the SNMP service to continue the attempt to resolve the variable bindings with other extension agents.

It is important to note that the SNMP service and the extension agent may need to exchange dynamically allocated memory during a call to the SnmpExtensionQuery function. The service dynamically allocates the object identifier in each SnmpVarBind structure it passes to the extension agent. However, the extension agent must release this memory in order to replace the object identifier when it processes a Get Next request. The extension agent allocates dynamic memory for variable-length object types. The SNMP service releases this memory after the object is placed in the response PDU.

In order to avoid heap corruption and memory leaks, both the SNMP service and the extension agent must use memory allocation routines that resolve to the same heap. The extension agent must use the SnmpUtilMemAlloc function to allocate memory that it passes to the SNMP service. It must use the SnmpUtilMemFree function to release the memory the service passes back to the extension agent. These functions are located in the utility dynamic-link library SNMPAPI.DLL.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpExtensionInit, SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpExtensionQueryEx

The Microsoft SNMP service calls the SnmpExtensionQueryEx function to process SNMP requests that specify variables in one or more MIB subtrees registered by SNMP extension agents. This function is an element of the SNMP Extension Agent API.

Note It is recommended that you use the SnmpExtensionQueryEx function, which supports SNMP version 2C (SNMPv2C) data types and multiphase SNMP SET operations. However, the extension agent must also export the SnmpExtensionQuery function if the extension agent runs on Windows NT 3.51 or 4.0. The SNMP service does not call the SnmpExtensionQuery function if the extension agent exports the SnmpExtensionQueryEx function.

BOOL SnmpExtensionQueryEx(
  DWORD dwRequestType,           // extension agent request type
  DWORD dwTransactionId,         // identifier of the incoming PDU
  SnmpVarBindList *pVarBindList, // pointer to variable binding list
  AsnOctetString *pContextInfo,  // pointer to context information
  AsnInteger32 *pErrorStatus,    // pointer to SNMPv2 error status
  AsnInteger32 *pErrorIndex      // pointer to the error index
);

Parameters

dwRequestType
Specifies the type of operation that the SNMP service is requesting the extension agent to perform. This parameter can be one of the following values.
Value | Meaning
SNMP_EXTENSION_GET | Retrieve the value or values of the specified variables.
SNMP_EXTENSION_GET_NEXT | Retrieve the value or values of the lexicographic successor of the specified variables.
SNMP_EXTENSION_SET_TEST | Validate the values of the specified variables. This operation maximizes the probability of a successful write during the COMMIT request.
SNMP_EXTENSION_SET_COMMIT | Write the new values to the specified variables.
SNMP_EXTENSION_SET_UNDO | Reset the values of the specified variables to their values before the COMMIT request.
SNMP_EXTENSION_SET_CLEANUP | Release the resources allocated in previous requests and operations.

For additional information about the SET request types, that is, those that begin with SNMP_EXTENSION_SET_, see the following Remarks section.

dwTransactionId
Specifies a DWORD variable that is the unique identifier of the incoming SNMP request PDU. The extension agent can use this value to correlate multiple calls by the SNMP service that involve the same PDU.
pVarBindList
Pointer to the variable binding list containing the variables of interest.
pContextInfo
Pointer to an octet string that contains user-defined context information.

The extension agent can use this parameter to store context information used during multiphase SNMP SET operations. The extension agent must release resources associated with this parameter during the CLEANUP request. The SNMP service does not release any resources associated with this parameter. For additional information, see the following Remarks section.

pErrorStatus
Pointer to a variable to receive the error status result. This parameter can be one of the following values defined by SNMPv2C.
Error code | Meaning
SNMP_ERRORSTATUS_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERRORSTATUS_TOOBIG | The agent could not place the results of the requested SNMP operation into a single SNMP message.
SNMP_ERRORSTATUS_NOSUCHNAME | The requested SNMP operation identified an unknown variable.
SNMP_ERRORSTATUS_BADVALUE | The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERRORSTATUS_READONLY | The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
SNMP_ERRORSTATUS_GENERR | An error other than one of those listed here occurred during the requested SNMP operation.
SNMP_ERRORSTATUS_NOACCESS | The specified SNMP variable is not accessible.
SNMP_ERRORSTATUS_WRONGTYPE | The value specifies a type that is inconsistent with the type required for the variable.
SNMP_ERRORSTATUS_WRONGLENGTH | The value specifies a length that is inconsistent with the length required for the variable.
SNMP_ERRORSTATUS_WRONGENCODING | The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
SNMP_ERRORSTATUS_WRONGVALUE | The value cannot be assigned to the variable.
SNMP_ERRORSTATUS_NOCREATION | The variable does not exist, and the agent cannot create it.
SNMP_ERRORSTATUS_INCONSISTENTVALUE | The value is inconsistent with values of other managed objects.
SNMP_ERRORSTATUS_RESOURCEUNAVAILABLE | Assigning the value to the variable requires allocation of resources that are currently unavailable.
SNMP_ERRORSTATUS_COMMITFAILED | No validation errors occurred, but no variables were updated.
SNMP_ERRORSTATUS_UNDOFAILED | No validation errors occurred. Some variables were updated because it was not possible to undo their assignment.
SNMP_ERRORSTATUS_AUTHORIZATIONERROR | An authorization error occurred.
SNMP_ERRORSTATUS_NOTWRITABLE | The variable exists but the agent cannot modify it.
SNMP_ERRORSTATUS_INCONSISTENTNAME | The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

pErrorIndex
Pointer to a variable to receive the error index result.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The SNMP service calls the SnmpExtensionQueryEx function multiple times to process an incoming SNMP SET request. The service can call SnmpExtensionQueryEx during the TEST request phase, the COMMIT request phase, the UNDO request phase, and the CLEANUP request phase.

TEST request

The SNMP service processes an SNMP SET request type by first calling the SnmpExtensionQueryEx function with a dwRequestType of SNMP_EXTENSION_SET_TEST. The service calls each extension agent responsible for the variable bindings in the request. Each extension agent must validate the variables in the variable binding list. They can optionally store any context information required for the following requests in the variable pointed to by the pContextInfo parameter.

If the TEST request fails, the service initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the TEST request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

COMMIT request

If all extension agents return TRUE to the TEST request, the SNMP service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_COMMIT dwRequestType. The service returns to the extension agent context information that the extension agent passed to the service. This is the context information the extension agent passed in the pContextInfo parameter during the TEST request. The extension agent can use the context information to update the values of the specified variables in an instrumentation-specific manner.

If the extension agent supports rollback processing, it can update the context information in the pContextInfo parameter at this time. The SNMP service passes the information back to the extension agent during the UNDO request.

If all extension agents return TRUE to the COMMIT request, the service calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

If any extension agent fails the COMMIT request, the service also initiates a CLEANUP request. The service calls each extension agent that previously returned TRUE to the COMMIT request again with the SnmpExtensionQueryEx function. The service calls each extension agent using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

CLEANUP request

The service returns to the extension agent the context information passed in the pContextInfo parameter during the TEST or COMMIT request. The extension agent must release the resources associated with the parameter at this time.

UNDO request

If any extension agent returns FALSE to the COMMIT request, the SNMP service terminates the COMMIT request. The service calls each extension agent that returned TRUE to the COMMIT request with a dwRequestType of SNMP_EXTENSION_SET_UNDO. This signals the extension agents that the COMMIT request failed, and they must initiate rollback processing.

The extension agents must attempt to reset the values of the variables of interest, back to the values they were before the COMMIT request failed. To do this, the extension agents use the context information returned in the pContextInfo parameter during the COMMIT request.

If any extension agent returns FALSE to the UNDO request, the entire SET operation fails with the error code SNMP_ERRORSTATUS_UNDOFAILED. If all extension agents return TRUE to the UNDO request, the SNMP SET operation fails with the error code set by the extension agent that failed the COMMIT request.

After the UNDO request the service always calls each extension agent with the SnmpExtensionQueryEx function, using the SNMP_EXTENSION_SET_CLEANUP dwRequestType.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionQuery, AsnOctetString, SnmpVarBindList


SnmpExtensionTrap

The Microsoft SNMP service calls the SnmpExtensionTrap function to retrieve information the service needs to generate traps for the SNMP extension agent. The service calls this function only after the extension agent sets the trap event handle to the signaled state during a call to the SnmpExtensionInit function. The SnmpExtensionTrap function is an element of the SNMP Extension Agent API.

BOOL SnmpExtensionTrap(
  AsnObjectIdentifier *pEnterpriseOid,  // generating enterprise
  AsnInteger32 *pGenericTrapId,         // generating trap type
  AsnInteger32 *pSpecificTrapId,        // enterprise-specific type
  AsnTimeticks *pTimeStamp,             // time stamp
  SnmpVarBindList *pVarBindList         // variable bindings
);

Parameters

pEnterpriseOid
[out] Pointer to an AsnObjectIdentifier structure to receive the object identifier of the enterprise that generated the trap. The SNMP service does not free the memory for this variable.
pGenericTrapId
[out] Pointer to a variable to receive an indication of the generic trap. This parameter can be one of the following values.
Value | Meaning
SNMP_GENERICTRAP_COLDSTART | The agent is initializing protocol entities on the managed mode. It may alter objects in its view.
SNMP_GENERICTRAP_WARMSTART | The agent is reinitializing itself but will not alter objects within its view.
SNMP_GENERICTRAP_LINKDOWN | An attached interface has changed from the up state to the down state. The first variable identifies the interface.
SNMP_GENERICTRAP_LINKUP | An attached interface has changed from the down state to the up state. The first variable identifies the interface.
SNMP_GENERICTRAP_AUTHFAILURE | An SNMP entity has sent an SNMP message, but has falsely claimed to belong to a known community.
SNMP_GENERICTRAP_EGPNEIGHLOSS | An EGP peer has changed to the down state. The first variable identifies the IP address of the EGP peer.
SNMP_GENERICTRAP_ENTERSPECIFIC | Signals an extraordinary event that is identified in the pSpecificTrapId parameter.

pSpecificTrapId
[out] Pointer to a variable to receive an indication of the specific trap generated.
pTimeStamp
[out] Pointer to a variable to receive the time stamp. It is recommended that you initialize this parameter with the value returned by a call to the SnmpSvcGetUptime function.
pVarBindList
[out] Pointer to the variable bindings list. The extension agent must allocate the memory for this parameter. The SNMP service frees the memory with a call to the SnmpUtilVarBindListFree function.

Return Values

If the SnmpExtensionTrap function returns a trap, the return value is TRUE. The SNMP service repeatedly calls the function until it returns a value of FALSE. For additional information, see the following Remarks section.

Remarks

The SNMP service repeatedly calls the SnmpExtensionTrap function when the phSubagentTrapEvent event handle is set to the signaled state. This handle is passed back during the call to the SnmpExtensionInit entry point function. The SnmpExtensionTrap function must return TRUE to indicate that the parameters contain valid data for a single trap. The function must return FALSE to indicate that the parameters do not represent valid trap data, and to stop the service's repeated calls.

Note that after the SNMP service sends a trap, it frees the memory associated with the variable binding list.

It is important to note that earlier documentation stated that the extension agent should dynamically allocate memory for the enterprise object identifier because the SNMP service would attempt to release the memory after sending a trap. The service will not release the memory associated with the enterprise object identifier. It is recommended that you return a pointer to a static AsnObjectIdentifier structure instead.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SetEvent, SnmpUtilMemAlloc, SnmpUtilVarBindListFree, SnmpVarBindList, SnmpSvcGetUptime, SnmpExtensionInit


SnmpMgrClose

The SnmpMgrClose function closes communications sockets and data structures associated with the specified session. This function is an element of the SNMP Management API.

BOOL SnmpMgrClose(
  LPSNMP_MGR_SESSION session  // SNMP session pointer
);

Parameters

session
[in] Pointer to an internal structure that specifies the session to close.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function may return Windows Sockets error codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOpen, SnmpMgrRequest


SnmpMgrCtl

The SnmpMgrCtl function sets an operating parameter associated with an SNMP session. This function is an element of the SNMP Management API.

BOOL SnmpMgrCtl(
  LPSNMP_MGR_SESSION session,
  DWORD dwCtlCode,
  LPVOID lpvInBuffer,
  DWORD cbInBuffer,
  LPVOID lpvOutBuffer,
  DWORD cbOutBuffer,
  LPDWORD lpcbBytesReturned
);

Parameters

session
[in] Pointer to an internal structure that specifies the session to which the control code applies.
dwCtlCode
[in] Specifies a value (a control code) that identifies the operation to perform.

Currently, MGMCTL_SETAGENTPORT is the only supported control code. Setting this code allows an SNMP management application to send requests to a remote agent that is "listening" for SNMP manager requests on an arbitrary port. For more information, see the lpvInBuffer and the cbInBuffer parameter descriptions.

lpvInBuffer
[in] Pointer to the buffer that contains the input parameters required for the operation.

When you specify the MGMCTL_SETAGENTPORT control code, this parameter must point to an unsigned integer that specifies the port number on which the remote agent will "listen" for SNMP manager requests. The port number must be in host-byte order.

cbInBuffer
[in] Specifies the size, in bytes, of the buffer pointed to by the lpvInBuffer parameter.

When you specify the MGMCTL_SETAGENTPORT control code, this parameter is equal to sizeof(UINT).

lpvOutBuffer
[out] Pointer to the buffer that receives the operation's output data.
cbOutBuffer
[out] Specifies the size, in bytes, of the buffer pointed to by the lpvOutBuffer parameter.
lpcbBytesReturned
[out] Pointer to a variable that receives the actual size, in bytes, of the data stored in the buffer pointed to by the lpvOutBuffer parameter.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can also return one of the following error codes.

Error code | Meaning
SNMP_MGMTAPI_INVALID_CTL | The dwCtlCode parameter does not specify a valid control code.
SNMP_MGMTAPI_INVALID_SESSION | The session parameter does not specify a valid SNMP session.
SNMP_MGMTAPI_INVALID_BUFFER | One or more of the lpvInBuffer, lpvOutBuffer, or lpcbBytesRequired parameters are invalid, or the cbInBuffer or cbOutBuffer parameter is too small.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOpen


SnmpMgrGetTrap

The SnmpMgrGetTrap function returns outstanding trap data that the caller has not received if trap reception is enabled. This function is an element of the SNMP Management API.

In addition to the information returned by this function, the SnmpMgrGetTrapEx function returns the address of the transport source and the community string of the trap.

BOOL SnmpMgrGetTrap(
  AsnObjectIdentifier *enterprise,   // generating enterprise
  AsnNetworkAddress *IPAddress,      // agent address
  AsnInteger *genericTrap,           // generic trap type
  AsnInteger *specificTrap,          // enterprise-specific type
  AsnTimeticks *timeStamp,           // time stamp
  SnmpVarBindList *variableBindings  // variable bindings
);

Parameters

enterprise
[out] Pointer to an AsnObjectIdentifier structure to receive the enterprise that generated the SNMP trap.
IPAddress
[out] Pointer to a variable to receive the address of the agent that generated the SNMP trap.
genericTrap
[out] Pointer to a variable to receive an indicator of the generic trap. This parameter can be one of the following values.
Value | Meaning
SNMP_GENERICTRAP_COLDSTART | The agent is initializing protocol entities on the managed mode. It may alter objects in its view.
SNMP_GENERICTRAP_WARMSTART | The agent is reinitializing itself but it will not alter objects in its view.
SNMP_GENERICTRAP_LINKDOWN | An attached interface has changed from the up state to the down state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_LINKUP | An attached interface has changed from the down state to the up state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_AUTHFAILURE | An SNMP entity has sent an SNMP message, but it has falsely claimed to belong to a known community.
SNMP_GENERICTRAP_EGPNEIGHLOSS | An EGP peer has changed to the down state. The first variable in the variable bindings list identifies the IP address of the EGP peer.
SNMP_GENERICTRAP_ENTERSPECIFIC | An extraordinary event has occurred and it is identified in the specificTrap parameter with an enterprise-specific value.

specificTrap
[out] Pointer to a variable to receive an indication of the specific trap generated.
timeStamp
[out] Pointer to a variable to receive the time stamp.
variableBindings
[out] Pointer to an SnmpVarBindList structure to receive the variable bindings list.

Return Values

If the function returns a trap, the return value is nonzero.

You should call the SnmpMgrGetTrap function repeatedly until it returns zero. The function may also return the following error codes.

Error code | Meaning
SNMP_MGMTAPI_TRAP_ERRORS | Indicates errors were encountered; traps are not accessible.
SNMP_MGMTAPI_NOTRAPS | Indicates no traps are available.
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error.

Remarks

The application must always call the SnmpMgrTrapListen function before calling the SnmpMgrGetTrap function. This is because the event handle pointed to by the phTrapAvailable parameter of the SnmpMgrTrapListen function enables the event-driven acquisition of SNMP traps. The SNMP Management API signals an application's event when the SNMP Trap Service delivers a trap.

The application can also poll the SnmpMgrGetTrap function for traps at regular intervals. In this case, the application should repeatedly call SnmpMgrGetTrap until the function returns zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrTrapListen, SnmpVarBindList, AsnObjectIdentifier


SnmpMgrGetTrapEx

The SnmpMgrGetTrapEx function returns outstanding trap data that the caller has not received if trap reception is enabled. In addition to the information returned by the SnmpMgrGetTrap function, this extended function returns the address of the transport source and the community string of the trap. This function is an element of the SNMP Management API.

BOOL SnmpMgrGetTrapEx(
  AsnObjectIdentifier *enterprise,
  AsnNetworkAddress *agentAddress,
  AsnNetworkAddress *sourceAddress,
  AsnInteger *genericTrap,
  AsnInteger *specificTrap,
  AsnOctetString *community,
  AsnTimeticks *timeStamp,
  SnmpVarBindList *variableBindings
);

Parameters

enterprise
[out] Pointer to an AsnObjectIdentifier structure to receive the enterprise that generated the SNMP trap.
agentAddress
[out] Pointer to a variable to receive the address of the agent that generated the SNMP trap; this information is retrieved from the SNMP protocol data unit (PDU).
sourceAddress
[out] Pointer to a variable to receive the address of the agent that generated the SNMP trap; this information is retrieved from the network transport.
genericTrap
[out] Pointer to a variable to receive an indicator of the generic trap. This parameter can be one of the following values.
Value | Meaning
SNMP_GENERICTRAP_COLDSTART | The agent is initializing protocol entities on the managed mode. It may alter objects in its view.
SNMP_GENERICTRAP_WARMSTART | The agent is reinitializing itself but it will not alter objects in its view.
SNMP_GENERICTRAP_LINKDOWN | An attached interface has changed from the up state to the down state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_LINKUP | An attached interface has changed from the down state to the up state. The first variable in the variable bindings list identifies the interface.
SNMP_GENERICTRAP_AUTHFAILURE | An SNMP entity has sent an SNMP message, but it has falsely claimed to belong to a known community.
SNMP_GENERICTRAP_EGPNEIGHLOSS | An EGP peer has changed to the down state. The first variable in the variable bindings list identifies the IP address of the EGP peer.
SNMP_GENERICTRAP_ENTERSPECIFIC | An extraordinary event has occurred. It is identified in the specificTrap parameter with an enterprise-specific value.

specificTrap
[out] Pointer to a variable to receive an indicator of the specific trap generated.
community
[out] Pointer to an AsnOctetString structure to receive the community string of the generated SNMP trap.
timeStamp
[out] Pointer to a variable to receive the time stamp.
variableBindings
[out] Pointer to an SnmpVarBindList structure to receive the variable bindings list.

Return Values

If the function returns a trap, the return value is nonzero.

You should call the SnmpMgrGetTrapEx function repeatedly until it returns zero. The function may also return the following error codes.

Error code | Meaning
SNMP_MGMTAPI_TRAP_ERRORS | Indicates errors were encountered; traps are not accessible.
SNMP_MGMTAPI_NOTRAPS | Indicates no traps are available.
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error.

Remarks

The application must always call the SnmpMgrTrapListen function before calling the SnmpMgrGetTrapEx function. This is because the event handle pointed to by the phTrapAvailable parameter of the SnmpMgrTrapListen function enables the event-driven acquisition of SNMP traps. The SNMP Management API signals an application's event when the SNMP Trap Service delivers a trap.

The application can also poll the SnmpMgrGetTrapEx function for traps at regular intervals. In this case, the application should repeatedly call SnmpMgrGetTrapEx until the function returns zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrTrapListen, AsnOctetString, AsnObjectIdentifier, SnmpVarBindList


SnmpMgrOidToStr

The SnmpMgrOidToStr function converts an internal object identifier structure to its string representation. This function is an element of the SNMP Management API.

BOOL SnmpMgrOidToStr(
  AsnObjectIdentifier *oid, // object identifier to convert
  LPSTR *string             // string object identifier representation
);

Parameters

oid
[in] Pointer to an object identifier variable to convert.
string
[out] Pointer to a null-terminated string to receive the converted value.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function may return Windows Sockets error codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrStrToOid


SnmpMgrOpen

The SnmpMgrOpen function initializes communications sockets and data structures, allowing communications with the specified SNMP agent. This function is an element of the SNMP Management API.

LPSNMP_MGR_SESSION SnmpMgrOpen(
  LPSTR lpAgentAddress,    // name and address of target SNMP agent
  LPSTR lpAgentCommunity,  // community for target SNMP agent
  INT nTimeOut,            // communication time-out in milliseconds
  INT nRetries             // communication time-out or retry count
);

Parameters

lpAgentAddress
[in] Pointer to a null-terminated string specifying either a dotted-decimal IP address or a host name that can be resolved to an IP address, an IPX address (in 8.12 notation), or an ethernet address.
lpAgentCommunity
[in] Pointer to a null-terminated string specifying the SNMP community name used when communicating with the agent specified in the lpAgentAddress parameter.
nTimeOut
[in] Specifies the communications time-out in milliseconds.
nRetries
[in] Specifies the communications retry count. The time-out specified in the nTimeOut parameter is doubled each time a retry attempt is transmitted.

Return Values

If the function succeeds, the return value is a pointer to an LPSNMP_MGR_SESSION structure. This structure is used internally and the programmer should not alter it.

If the function fails, the return value is NULL. To get extended error information, call GetLastError. GetLastError may return the SNMP_MEM_ALLOC_ERROR error code, which indicates a memory allocation error.

This function may also return Windows Sockets error codes.

The name and address of the SNMP target, or the string pointed to by the lpAgentAddress parameter, should conform to one of the following forms.

Name/Address | Form (example)
IP Address | 157.57.8.160
IP Hostname | merlin.microsoft.com
Ethernet Address | 00aa00bbccdd
IPX Address | 00006112.00aa00bbccdd

Remarks

Names can be provided for agents only if TCP/IP is loaded and the names are TCP/IP host names. NetBIOS names cannot be supplied for IPX hosts.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrClose, SnmpMgrRequest


SnmpMgrRequest

The SnmpMgrRequest function requests the specified operation be performed with the specified agent. This function is an element of the SNMP Management API.

SNMPAPI SnmpMgrRequest(
  LPSNMP_MGR_SESSION session,         // SNMP session pointer
  BYTE requestType,                   // Get, GetNext, or Set
  SnmpVarBindList *variableBindings,  // variable bindings
  AsnInteger *errorStatus,            // SNMPv1 error status
  AsnInteger *errorIndex              // error index
);

Parameters

session
[in] Pointer to an internal structure that specifies the session that will perform the request.
requestType
[in] Specifies the SNMP request type. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_PDU_GET | Retrieve the value or values of the specified variables.
SNMP_PDU_GETNEXT | Retrieve the value or values of the lexicographic successor of the specified variable.
SNMP_PDU_SET | Write a value within a specific variable.

Note that PDU request types have been renamed. For additional information, see SNMP Variable Types and Request PDU Types.

variableBindings
[in/out] Pointer to the variable bindings list.
errorStatus
[out] Pointer to a variable in which the error status result will be returned. This parameter can be one of the following values defined by SNMPv1.
Value | Meaning
SNMP_ERRORSTATUS_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERRORSTATUS_TOOBIG | The agent could not place the results of the requested operation into a single SNMP message.
SNMP_ERRORSTATUS_NOSUCHNAME | The requested operation identified an unknown variable.
SNMP_ERRORSTATUS_BADVALUE | The requested operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERRORSTATUS_READONLY | The requested operation tried to change a variable that was not allowed to change according to the community profile of the variable.
SNMP_ERRORSTATUS_GENERR | An error other than one of those listed here occurred during the requested operation.

errorIndex
[out] Pointer to a variable in which the error index result will be returned.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is NULL. To get extended error information, call GetLastError. GetLastError may return one of the following error codes.

Error code | Meaning
SNMP_MGMTAPI_TIMEOUT | The request timed-out.
SNMP_MGMTAPI_SELECT_FDERRORS | Unexpected error file descriptors indicated by the Windows Sockets select function.

Remarks

Retries and time-outs are supplied to the SnmpMgrOpen function. Each variable in the variable bindings list must be initialized to type ASN_NULL for Get and Get Next requests.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOpen, SnmpMgrClose


SnmpMgrStrToOid

The SnmpMgrStrToOid function converts the string format of an object identifier to its internal object identifier structure. This function is an element of the SNMP Management API.

BOOL SnmpMgrStrToOid(
  LPSTR string,             // string to convert
  AsnObjectIdentifier *oid  // object identifier representation
);

Parameters

string
[in] Pointer to a null-terminated string to convert.
oid
[out] Pointer to an object identifier variable to receive the converted value.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function does not return Windows Sockets error codes.

Remarks

If an application passes a valid object identifier to SnmpMgrStrToOid, yet is unable to obtain the requested variable, then the syntax of the system group and object identifier is incorrect. This occurs because SnmpMgrStrToOid assumes that the object identifier is under the Internet MIB of the management subtree.

You must always precede the object identifier with a period (.) to obtain the correct system group (for example, ".1.3.6.1.2.1.1"). If an application passes the variable "1.3.6.1.2.1.1", SnmpMgrStrToOid cannot interpret the object identifier correctly.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrOidToStr


SnmpMgrTrapListen

The SnmpMgrTrapListen function registers the ability of an SNMP manager application to receive SNMP traps from the SNMP Trap Service. This function is an element of the SNMP Management API.

BOOL SnmpMgrTrapListen(
  HANDLE *phTrapAvailable  // event handle indicating a trap
                           //  is available
);

Parameters

phTrapAvailable
[out] Pointer to an event handle to receive an indication that there are traps available, and that the application should call the SnmpMgrGetTrap function.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return any of the following error codes.

Error code | Description
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error.
SNMP_MGMTAPI_TRAP_DUPINIT | Indicates that this function has already been called.
SNMP_MGMTAPI_TRAP_ERRORS | Indicates one or more errors occurred; traps are not accessible. The application can attempt to call the function again.

This function may return other system errors as well.

Remarks

It is important to note that for users who are not administrators the SnmpMgrTrapListen function succeeds on Windows NT® 4.0 and Windows® 2000 only if the SNMP trap service has been started.

The application must always call the SnmpMgrTrapListen function before calling the SnmpMgrGetTrap function. This is because the event handle pointed to by the phTrapAvailable parameter enables the event-driven acquisition of SNMP traps. The SNMP Management API signals an application's event when the SNMP Trap Service delivers a trap.

The application can also poll the SnmpMgrGetTrap function for traps at regular intervals. In this case, the application should repeatedly call SnmpMgrGetTrap until the function returns zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Mgmtapi.h.
Library: Use Mgmtapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpMgrGetTrap


SnmpSvcGetUptime

The SnmpSvcGetUptime function retrieves the number of centiseconds that the SNMP service has been running. This function is an element of the SNMP Utility API.

DWORD SnmpSvcGetUptime();

Parameters

This function has no parameters.

Return Values

The function returns a DWORD value that is the number of centiseconds the SNMP service has been running.

Remarks

An extension agent should call the SnmpSvcGetUptime function only if the extension agent DLL is loaded within the address space of the SNMP service.

The SNMP extension agent DLL is encouraged to use the SnmpSvcGetUptime function to retrieve the number of centiseconds that the SNMP service has been running. Extension agents should use SnmpSvcGetUptime rather than calculate the uptime using the dwUptimeReference parameter. The service passes this parameter to the extension agent as the result of a call to the SnmpExtensionInit function. Because the dwUptimeReference parameter stores the elapsed time as a DWORD value in milliseconds, the time can wrap to zero and reflect an inaccurate time interval.

An extension agent that sends traps must initialize the timeStamp parameter to the SnmpExtensionTrap function with the value returned by a call to the SnmpSvcGetUptime function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpExtensionInit, SnmpExtensionTrap


SnmpSvcSetLogLevel

The SnmpSvcSetLogLevel function adjusts the level of detail of the debug output from the SNMP service and from SNMP extension agents using the SnmpUtilDbgPrint function. This function is an element of the SNMP Utility API.

VOID SnmpSvcSetLogLevel(
  INT nLogLevel  // level of severity of the event
);

Parameters

nLogLevel
Specifies a signed integer variable that indicates the level of detail of the debug output from the SnmpUtilDbgPrint function. This parameter can be one of the following values.
Value | Meaning
SNMP_LOG_SILENT | Disable all debugging output.
SNMP_LOG_FATAL | Display fatal errors only.
SNMP_LOG_ERROR | Display recoverable errors.
SNMP_LOG_WARNING | Display warnings and recoverable errors.
SNMP_LOG_TRACE | Display trace information.
SNMP_LOG_VERBOSE | Display verbose trace information.

Remarks

Extension agents are encouraged to use the SnmpSvcSetLogType and SnmpSvcSetLogLevel functions during development to adjust the output of debugging information. Extension agents can integrate the information with the debug output from the SNMP service.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilDbgPrint, SnmpSvcSetLogType


SnmpSvcSetLogType

The SnmpSvcSetLogType function adjusts the destination for the debug output from the SNMP service and from SNMP extension agents using the SnmpUtilDbgPrint function. This function is an element of the SNMP Utility API.

VOID SnmpSvcSetLogType(
  INT nLogType  // destination for debug output
);

Parameters

nLogType
Specifies a signed integer variable that represents the destination for the debug output from the SnmpUtilDbgPrint function. This parameter can be one of the following values.
Value | Meaning
SNMP_OUTPUT_TO_CONSOLE | The destination for the debug output is a console window.
SNMP_OUTPUT_TO_LOGFILE | The destination for the debug output is the SNMPDBG.LOG file in the SYSTEM32 directory.
SNMP_OUTPUT_TO_DEBUGGER | The destination for the debug output is a debugger utility.

Remarks

Extension agents are encouraged to use the SnmpSvcSetLogType and SnmpSvcSetLogLevel functions during development to adjust the output of debugging information. Extension agents can integrate the information with the debug output from the SNMP service.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilDbgPrint, SnmpSvcSetLogLevel


SnmpUtilAsnAnyCpy

The SnmpUtilAsnAnyCpy function copies the variable pointed to by the pAnySrc parameter to the pAnyDst parameter. The function allocates any necessary memory for the destination's copy. The SnmpUtilAsnAnyCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilAsnAnyCpy(
  AsnAny *pAnyDst,  // destination structure
  AsnAny *pAnySrc   // source structure
);

Parameters

pAnyDst
Pointer to an AsnAny structure to receive the copy.
pAnySrc
Pointer to an AsnAny structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilAsnAnyFree function to free the memory that the SnmpUtilAsnAnyCpy function allocates for the destination structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny, SnmpUtilAsnAnyFree


SnmpUtilAsnAnyFree

The SnmpUtilAsnAnyFree function frees the memory allocated for the specified AsnAny structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilAsnAnyFree(
  AsnAny *pAny  // pointer to structure to free
);

Parameters

pAny
Pointer to an AsnAny structure whose memory should be freed.

Remarks

Call the SnmpUtilAsnAnyFree function to free the memory that the SnmpUtilAsnAnyCpy function allocates.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny, SnmpUtilAsnAnyCpy


SnmpUtilDbgPrint

The SnmpUtilDbgPrint function enables debugging output from the SNMP service. This function is an element of the SNMP Utility API.

VOID SnmpUtilDbgPrint(
  INT nLogLevel,  // level of severity of event
  LPSTR szFormat  // pointer to a format string
);

Parameters

nLogLevel
Specifies a signed integer variable that indicates the level of detail of the log event. This parameter can be one of the following values.
Value | Meaning
SNMP_LOG_SILENT | Disable all debugging output.
SNMP_LOG_FATAL | Display fatal errors only.
SNMP_LOG_ERROR | Display recoverable errors.
SNMP_LOG_WARNING | Display warnings and recoverable errors.
SNMP_LOG_TRACE | Display trace information.
SNMP_LOG_VERBOSE | Display verbose trace information.

szFormat
Pointer to a null-terminated format string that is similar to the standard C library function printf style.

Remarks

Extension agents are encouraged to use this function during development to enable debug output from the SNMP service.

Use the SnmpSvcSetLogLevel function to set the level of detail of the debug output from the SNMP service or from an extension agent's call to the SnmpUtilDbgPrint function. Call the SnmpSvcSetLogType function to specify the destination for the debug output.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpSvcSetLogType, SnmpSvcSetLogLevel


SnmpUtilIdsToA

The SnmpUtilIdsToA function converts an object identifer (OID) to a null-terminated string. This function is an element of the SNMP Utility API.

LPSTR SnmpUtilIdsToA(
  UINT *Ids,     // object identifier to convert
  UINT IdLength  // number of elements
);

Parameters

Ids
[in] Pointer to an array of unsigned integers. The array contains the sequence of numbers that the OID contains. The IdLength parameter specifies the array's length.

For more information, see the following Return Values and Remarks sections.

IdLength
[in] Specifies the number of elements in the array pointed to by the Ids parameter.

Return Values

The function returns a null-terminated string that contains the string representation of the array of numbers pointed to by the Ids parameter. The string contains a sequence of numbers separated by periods ('.'); for example, 1.3.6.1.4.1.311.

If the Ids parameter is null, or if the IdLength parameter specifies zero, the function returns the string "<null oid>".

The maximum length of the returned string is 256 characters. If the string's length exceeds 256 characters, the string is truncated and terminated with a sequence of three periods ('...').

Remarks

The SnmpUtilIdsToA function can assist with the debugging of SNMP applications.

Note that the following memory restrictions apply when you call SnmpUtilIdsToA:

  • The Ids parameter must point to a valid memory block of at least IdLength integers, or the function call results in an access violation exception.
  • The string returned by SnmpUtilIdsToA resides in memory that the SNMP Utility API allocates. The application should not make any assumptions about the memory allocation. The data is guaranteed to be valid until you call SnmpUtilIdsToA again, so before calling the function again you should copy the data to another location.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidToA


SnmpUtilMemAlloc

The SnmpUtilMemAlloc function allocates dynamic memory from the process heap. This function is an element of the SNMP Utility API.

LPVOID SnmpUtilMemAlloc(
  UINT nBytes  // bytes to allocate for object
);

Parameters

nBytes
[in] Specifies the number of bytes to allocate for the memory object.

Return Values

If the function succeeds, the return value is a pointer to the newly allocated memory object.

If the function fails, the return value is NULL.

Remarks

Use the SnmpUtilMemFree function to release memory that the SnmpUtilMemAlloc function allocates.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemFree, SnmpUtilMemReAlloc


SnmpUtilMemFree

The SnmpUtilMemFree function frees the specified memory object. This function is an element of the SNMP Utility API.

VOID SnmpUtilMemFree(
  LPVOID pMem  // pointer to memory object to release
);

Parameters

pMem
[in/out] Pointer to the memory object to release.

Remarks

Call the SnmpUtilMemAlloc function to allocate the memory for the object.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemAlloc, SnmpUtilMemReAlloc


SnmpUtilMemReAlloc

The SnmpUtilMemReAlloc function changes the size of the specified memory object. This function is an element of the SNMP Utility API.

LPVOID SnmpUtilMemReAlloc(
  LPVOID pMem,  // pointer to memory object
  UINT nBytes   // bytes to allocate
);

Parameters

pMem
[in] Pointer to the memory object to resize.
nBytes
[in] Specifies the number of bytes to allocate for the new memory object.

Return Values

If the function succeeds, the return value is a pointer to the newly allocated memory object.

If the function fails, the return value is NULL.

Remarks

Call the SnmpUtilMemFree function to release memory that the SnmpUtilMemReAlloc function allocates.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemAlloc, SnmpUtilMemFree


SnmpUtilOctetsCmp

The SnmpUtilOctetsCmp function compares two octet strings. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsCmp(
  AsnOctetString *pOctets1,  // first octet string
  AsnOctetString *pOctets2   // second octet string
);

Parameters

pOctets1
Pointer to an AsnOctetString structure to compare.
pOctets2
Pointer to a second AsnOctetString structure to compare.

Return Values

The function returns a value greater than zero if pOctets1 is greater than pOctets2, zero if pOctets1 equals pOctets2, and less than zero if pOctets1 is less than pOctets2.

Remarks

The SnmpUtilOctetsCmp function calls the SnmpUtilOctetsNCmp function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsNCmp


SnmpUtilOctetsCpy

The SnmpUtilOctetsCpy function copies the variable pointed to by the pOctetsSrc parameter to the variable pointed to by the pOctetsDst parameter. The function allocates any necessary memory for the destination's copy. The SnmpUtilOctetsCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsCpy(
  AsnOctetString *pOctetsDst,  // destination octet string
  AsnOctetString *pOctetsSrc   // source octet string
);

Parameters

pOctetsDst
Pointer to an AsnOctetString structure to receive the copy.
pOctetsSrc
Pointer to an AsnOctetString structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilOctetsFree function to free the memory that the SnmpUtilOctetsCpy function allocates for the destination structure.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsFree


SnmpUtilOctetsFree

The SnmpUtilOctetsFree function frees the memory allocated for the specified octet string. This function is an element of the SNMP Utility API.

VOID SnmpUtilOctetsFree(
  AsnOctetString *pOctets  // octet string to free
);

Parameters

pOctets
Pointer to an AsnOctetString structure whose memory should be freed.

Remarks

Call the SnmpUtilOctetsFree function to free the memory that the SnmpUtilOctetsCpy function allocates.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsCpy


SnmpUtilOctetsNCmp

The SnmpUtilOctetsNCmp function compares two octet strings. The function compares the subidentifiers in the strings until it reaches the number of subidentifiers specified by the nChars parameter. SnmpUtilOctetsNCmp is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOctetsNCmp(
  AsnOctetString *pOctets1,  // first octet string
  AsnOctetString *pOctets2,  // second octet string
  UINT nChars                // maximum length to compare
);

Parameters

pOctets1
Pointer to an AsnOctetString structure to compare.
pOctets2
Pointer to a second AsnOctetString structure to compare.
nChars
Specifies the number of subidentifiers to compare.

Return Values

The function returns a value greater than zero if pOctets1 is greater than pOctets2, zero if pOctets1 equals pOctets2, and less than zero if pOctets1 is less than pOctets2.

Remarks

The SnmpUtilOctetsCmp function calls the SnmpUtilOctetsNCmp function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnOctetString, SnmpUtilOctetsCmp


SnmpUtilOidAppend

The SnmpUtilOidAppend function appends the source object identifier to the destination object identifier. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidAppend(
  AsnObjectIdentifier *pOidDst,  // destination object identifier
  AsnObjectIdentifier *pOidSrc   // source object identifier
);

Parameters

pOidDst
[in/out] Pointer to an AsnObjectIdentifier structure to receive the source structure.
pOidSrc
[in] Pointer to an AsnObjectIdentifier structure to append.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. This function does not generate Windows Sockets errors. The application should call the GetLastError function. GetLastError may return the following error codes.

Error code | Description
SNMP_BERAPI_OVERFLOW | Indicates an overflow condition
SNMP_MEM_ALLOC_ERROR | Indicates a memory allocation error

Remarks

The SnmpUtilOidAppend function calls the SnmpUtilMemReAlloc function. The SnmpUtilMemReAlloc function expands the buffer for the destination object identifier.

Call the SnmpUtilOidFree function to free memory that the SnmpUtilOidAppend function allocates for the destination.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilMemReAlloc, SnmpUtilOidFree


SnmpUtilOidCmp

The SnmpUtilOidCmp function compares two object identifiers. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidCmp(
  AsnObjectIdentifier *pOid1,  // first object identifier
  AsnObjectIdentifier *pOid2   // second object identifier
);

Parameters

pOid1
[in] Pointer to an AsnObjectIdentifier structure to compare.
pOid2
[in] Pointer to a second AsnObjectIdentifier structure to compare.

Return Values

The function returns a value greater than zero if pOid1 is greater than pOid2, zero if pOid1 equals pOid2, and less than zero if pOid1 is less than pOid2.

Remarks

The SnmpUtilOidCmp function calls the SnmpUtilOidNCmp function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidNCmp


SnmpUtilOidCpy

The SnmpUtilOidCpy function copies the variable pointed to by the pOidSrc parameter to the pOidDst parameter, allocating any necessary memory for the destination's copy. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidCpy(
  AsnObjectIdentifier *pOidDst,  // destination object identifier
  AsnObjectIdentifier *pOidSrc   // source object identifier
);

Parameters

pOidDst
[out] Pointer to an AsnObjectIdentifier structure to receive the copy.
pOidSrc
[in] Pointer to an AsnObjectIdentifier structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilOidFree function to free memory that the SnmpUtilOidCpy function allocates for the destination structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidFree


SnmpUtilOidFree

The SnmpUtilOidFree function frees the memory allocated for the specified object identifier. This function is an element of the SNMP Utility API.

VOID SnmpUtilOidFree(
  AsnObjectIdentifier *pOid  // object identifier to free
);

Parameters

pOid
[in/out] Pointer to an AsnObjectIdentifier structure whose memory should be freed.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidAppend


SnmpUtilOidNCmp

The SnmpUtilOidNCmp function compares two object identifiers. The function compares the subidentifiers in the variables until it reaches the number of subidentifiers specified by the nSubIds parameter. SnmpUtilOidNCmp is an element of the SNMP Utility API.

SNMPAPI SnmpUtilOidNCmp(
  AsnObjectIdentifier *pOid1,  // first object identifier
  AsnObjectIdentifier *pOid2,  // second object identifier
  UINT nSubIds                 // maximum length to compare
);

Parameters

pOid1
[in] Pointer to an AsnObjectIdentifier structure to compare.
pOid2
[in] Pointer to a second AsnObjectIdentifier structure to compare.
nSubIds
[in] Specifies the number of subidentifiers to compare.

Return Values

The function returns a value greater than zero if pOid1 is greater than pOid2, zero if pOid1 equals pOid2, and less than zero if pOid1 is less than pOid2.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilOidCmp


SnmpUtilOidToA

The SnmpUtilOidToA function converts an object identifier (OID) to a null-terminated string. This function is an element of the SNMP Utility API.

LPSTR SnmpUtilOidToA(
  AsnObjectIdentifier *Oid  // object identifier to convert
);

Parameters

Oid
[in] Pointer to an AsnObjectIdentifier structure to convert.

Return Values

The function returns a null-terminated string of characters that contains the string representation of the object identifier pointed to by the Oid parameter.

Remarks

The SnmpUtilOidToA function can assist with the debugging of SNMP applications.

For more information, see the SnmpUtilIdsToA function. SnmpUtilOidToA calls SnmpUtilIdsToA internally to format the string.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilIdsToA, AsnObjectIdentifier


SnmpUtilPrintAsnAny

The SnmpUtilPrintAsnAny function prints the value of the Any parameter to the standard output. This function is an element of the SNMP Utility API.

VOID SnmpUtilPrintAsnAny(
  AsnAny *pAny  // pointer to value to print
);

Parameters

pAny
[in] Pointer to an AsnAny structure for a value to print.

Remarks

Use the SnmpUtilPrintAsnAny function for debugging and development purposes. This function does not generally print the data in a form that a manager application would typically need.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, AsnAny


SnmpUtilPrintOid

The SnmpUtilPrintOid function formats the specified object identifier (OID) and prints the result to the standard output device. This function is an element of the SNMP Utility API.

VOID SnmpUtilPrintOid(
  AsnObjectIdentifier *Oid  // object identifier to print
);

Parameters

Oid
[in] Pointer to an AsnObjectIdentifier structure to print.

Remarks

The SnmpUtilPrintOid function can assist with the debugging of command-line SNMP applications. The function prints the object identifier as a sequence of numbers separated by periods ('.'); for example, 1.3.6.1.4.1.311.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpUtilDbgPrint, AsnObjectIdentifier


SnmpUtilVarBindCpy

The SnmpUtilVarBindCpy function copies the specified SnmpVarBind structure, and allocates any memory necessary for the destination structure. The SnmpUtilVarBindCpy function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilVarBindCpy(
  SnmpVarBind *pVbDst,  // destination variable bindings
  SnmpVarBind *pVbSrc   // source variable bindings
);

Parameters

pVbDst
[out] Pointer to an SnmpVarBind structure to receive the copy.
pVbSrc
[in] Pointer to an SnmpVarBind structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilVarBindFree function to free memory that the SnmpUtilVarBindCpy function allocates for the destination structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpUtilVarBindFree


SnmpUtilVarBindListCpy

The SnmpUtilVarBindListCpy function copies the specified SnmpVarBindList structure, and allocates any necessary memory for the destination's copy. This function is an element of the SNMP Utility API.

SNMPAPI SnmpUtilVarBindListCpy(
  SnmpVarBindList *pVblDst,  // destination variable bindings list
  SnmpVarBindList *pVblSrc   // source variable bindings list
);

Parameters

pVblDst
[out] Pointer to an SnmpVarBindList structure to receive the copy.
pVblSrc
[in] Pointer to an SnmpVarBindList structure to copy.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

Call the SnmpUtilVarBindListFree function to free memory that the SnmpUtilVarBindListCpy function allocates for the destination structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBindList, SnmpUtilVarBindListFree, SnmpUtilOidCpy


SnmpUtilVarBindFree

The SnmpUtilVarBindFree function frees the memory allocated for an SnmpVarBind structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilVarBindFree(
  SnmpVarBind *pVb  // variable binding to free
);

Parameters

pVb
[in/out] Pointer to an SnmpVarBind structure whose memory should be freed.

Return Values

None.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBind, SnmpUtilVarBindListFree


SnmpUtilVarBindListFree

The SnmpUtilVarBindListFree function frees the memory allocated for an SnmpVarBindList structure. This function is an element of the SNMP Utility API.

VOID SnmpUtilVarBindListFree(
  SnmpVarBindList *pVbl  // variable bindings list to free
);

Parameters

pVbl
[in/out] Pointer to an SnmpVarBindList structure whose allocated memory should be freed.

Return Values

No return value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.
Library: Use Snmpapi.lib.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Functions, SnmpVarBindList, SnmpUtilVarBindFree


SNMP Structures

The following structures are used with SNMP.

AsnAny
AsnCounter64
AsnObjectIdentifier
AsnOctetString
SnmpVarBind
SnmpVarBindList


AsnAny

The AsnAny structure contains an SNMP variable type and value. This structure is a member of the SnmpVarBind structure that is used as a parameter in many of the SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
    BYTE asnType;
     union {
       AsnInteger32         number;      // ASN_INTEGER
                                         // ASN_INTEGER32
       AsnUnsigned32        unsigned32;  // ASN_UNSIGNED32
       AsnCounter64         counter64;   // ASN_COUNTER64
       AsnOctetString       string;      // ASN_OCTETSTRING
       AsnBits              bits;        // ASN_BITS
       AsnObjectIdentifier  object;      // ASN_OBJECTIDENTIFIER
       AsnSequence          sequence;    // ASN_SEQUENCE
       AsnIPAddress         address;     // ASN_IPADDRESS
       AsnCounter32         counter;     // ASN_COUNTER32
       AsnGauge32           gauge;       // ASN_GAUGE32
       AsnTimeticks         ticks;       // ASN_TIMETICKS
       AsnOpaque            arbitrary;   // ASN_OPAQUE
} asnValue;
} AsnAny;

Members

asnType
Indicates the variable's type. This member must be only one of the following values.
Value | Meaning
ASN_INTEGER | Indicates a 32-bit signed integer variable.
ASN_INTEGER32 | Indicates a 32-bit signed integer variable.
ASN_UNSIGNED32 | Indicates a 32-bit unsigned integer variable.
ASN_COUNTER64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
ASN_OCTETSTRING | Indicates an octet string variable.
ASN_BITS | Indicates a variable that is an enumeration of named bits.
ASN_OBJECTIDENTIFIER | Indicates an object identifier variable.
ASN_SEQUENCE | Indicates an ASN sequence variable.
ASN_IPADDRESS | Indicates an IP address variable.
ASN_COUNTER32 | Indicates a counter variable.
ASN_GAUGE32 | Indicates a gauge variable.
ASN_TIMETICKS | Indicates a timeticks variable.
ASN_OPAQUE | Indicates an opaque variable.

asnValue
Contains the variable's value. This member can be only one of the following values.
Value | Meaning
number | Accesses a 32-bit signed integer variable.
unsigned32 | Accesses a 32-bit unsigned integer variable.
counter64 | Accesses a counter variable that increases until it reaches a maximum value of (2^64) – 1.
String | Accesses an octet string variable.
bits | Accesses a variable that is an enumeration of named bits with non-negative, contiguous values, starting at zero.
Object | Accesses an object identifier variable.
sequence | Accesses an ASN sequence variable.
address | Accesses an IP address variable.
counter | Accesses a counter variable that increases until it reaches a maximum value of (2^32) – 1.
Gauge | Accesses a gauge variable.
ticks | Accesses a timeticks counter variable that is relative to a specific timer event.
Arbitrary | Accesses an opaque variable.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpVarBind, SnmpExtensionMonitor


AsnCounter64

The AsnCounter64 structure contains a 64-bit unsigned integer value and represents a 64-bit counter. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
  ULONG   LowPart;    // low-order 32 bits
  ULONG   HighPart;   // high-order 32 bits
} AsnCounter64;

Members

LowPart
Specifies the low-order 32 bits of the counter.
HighPart
Specifies the high-order 32 bits of the counter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, AsnAny


AsnObjectIdentifier

The AsnObjectIdentifier structure represents object identifiers. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
  UINT idLength;  // length of oid
  UINT * ids ;    // pointer to oid array
} AsnObjectIdentifier;

Members

idLength
Specifies the number of integers in the object identifier.
ids
Pointer to an array of integers that represents the object identifier.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures


AsnOctetString

The AsnOctetString structure contains octet quantities, usually bytes. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
  BYTE  * stream;  // pointer to octet stream
  UINT  length;    // number of octets in stream
  BOOL  dynamic;   // dynamic allocation flag
} AsnOctetString;

Members

stream
Pointer to the octet stream.
length
The number of octets in the data stream.
dynamic
Flag that specifies whether the data stream has been dynamically allocated with the SnmpUtilMemAlloc function.

Remarks

Use the AsnOctetString structure to transfer string values. For example, use it to transfer the string that represents a computer name as a MIB object value.

You must check the flag specified in the dynamic member before you release the data stream of an octet string. Call the SnmpUtilMemFree function only if the dynamic member is set to TRUE.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpUtilMemFree, SnmpUtilMemAlloc


SnmpVarBind

The SnmpVarBind structure represents an SNMP variable binding. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
  AsnObjectName   name;   // variable name
  AsnObjectSyntax value;  // variable value
} SnmpVarBind;

Members

name
Indicates the variable's name, as an object identifier.
value
Contains the variable's value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures


SnmpVarBindList

The SnmpVarBindList structure represents an SNMP variable bindings list. This structure is used by multiple SNMP functions. This structure is not used by the WinSNMP API functions.

typedef struct {
  SnmpVarBind *list;   // pointer to variable bindings
  UINT           len;  // number of variable binding entries
} SnmpVarBindList;

Members

list
A pointer that references an array to access individual variable bindings.
len
Contains the number of variable bindings in the list.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Snmp.h.

See Also

Simple Network Management Protocol (SNMP) Overview, SNMP Structures, SnmpVarBind


SNMP Variable Types and Request PDU Types

The definitions for some SNMP variable types and request PDU types have changed. The Snmp.h file maps old types to the corresponding new types.

Modified SNMP Variable Types

You should use the new SNMP variable types listed in the following table when you develop manager applications that use the Microsoft SNMP Management API. The table lists the old SNMP variable types with the corresponding new variable types.

Old variable type | New variable type
ASN_RFC1155_IPADDRESS | ASN_IPADDRESS
ASN_RFC1155_COUNTER | ASN_COUNTER32
ASN_RFC1155_GAUGE | ASN_GAUGE32
ASN_RFC1155_TIMETICKS | ASN_TIMETICKS
ASN_RFC1155_OPAQUE | ASN_OPAQUE
ASN_RFC1213_DISPSTRING | ASN_OCTETSTRING

Modified SNMP PDU Request Types

You should use the new SNMP PDU types listed in the following table when you develop manager applications that use the Microsoft SNMP Management API. The table lists the old SNMP PDU types with the corresponding new PDU types.

Old PDU type | New PDU type
ASN_RFC1157_GETREQUEST | SNMP_PDU_GET
ASN_RFC1157_GETNEXTREQUEST | SNMP_PDU_GETNEXT
ASN_RFC1157_GETRESPONSE | SNMP_PDU_RESPONSE
ASN_RFC1157_SETREQUEST | SNMP_PDU_SET
ASN_RFC1157_TRAP | SNMP_PDU_V1TRAP


WinSNMP API

The Microsoft® Windows® SNMP Application Programming Interface (the WinSNMP API) versions 1.1a and 2.0 allow you to develop SNMP-based network management applications that execute in the Windows® 2000 operating environment. The Simple Network Management Protocol (SNMP) is a request-response protocol that transfers management information between protocol entities.

WinSNMP has been jointly developed with the cooperation, input, and support from several companies, associations and individuals.

The first part of this overview provides information about the WinSNMP 2.0 Addendum, SNMP versions, and a list of the relevant Requests for Comments (RFCs). It also describes the WinSNMP model, and the components and features of the Microsoft WinSNMP implementation. It also provides information about data management and communications concepts you need to program in the WinSNMP environment.

The second section discusses the WinSNMP functions and the following related WinSNMP programming tasks:

  • Opening and closing a WinSNMP application
  • Opening and closing a WinSNMP session
  • Managing traps and notifications
  • Working with variable binding lists
  • Working with protocol data units
  • Sending SNMP messages
  • Receiving SNMP messages
  • Managing object identifiers
  • Freeing WinSNMP descriptors
  • Setting the entity and context translation mode
  • Managing the retransmission policy
  • Writing WinSNMP applications with multiple threads
  • Registering an SNMP agent application

You should be familiar with the basic concepts of SNMP and Windows programming before reading this overview. For more information about SNMP, see Simple Network Management Protocol and the relevant Requests for Comments (RFCs) which are published by the Internet Engineering Task Force (IETF).


About the WinSNMP API

The WinSNMP API is an interface for the development of SNMP-enabled network management applications.

The WinSNMP API provides the following features:

  • SNMP-enabling technology for network management applications
  • SNMP version 1 (SNMPv1) and SNMP version 2C (SNMPv2C) support

In addition to SNMP manager operations, WinSNMP API version 2.0 also supports SNMP agent operations.

The WinSNMP API supports 32-bit applications, and it executes in single- and multi-threaded environments. Support for the WinSNMP API is available for applications that execute in the Windows 2000 operating environment.


About the WinSNMP 2.0 Addendum

The WinSNMP version 2.0 Addendum is an update to the WinSNMP Manager API specification, version 1.1a. (At this time no specification defines version 2.0 of the WinSNMP API.) The Addendum was jointly developed with the cooperation, input, and support from several companies, associations, and individuals.

The WinSNMP 1.1a specification defines the WinSNMP Manager application programming interface for developing SNMP-based network management applications. In the WinSNMP version 2.0 Addendum, the interface is renamed as the WinSNMP API. This is because WinSNMP 2.0 supports both agent and manager SNMP operations. You should be familiar with both documents if you are programming in the WinSNMP environment.

The Microsoft WinSNMP implementation is compliant with WinSNMP 2.0. It supports all the functions and operations defined in both the WinSNMP 1.1a specification and the WinSNMP 2.0 Addendum.


About SNMP Versions

The original Internet standard Network Management Framework, described in RFCs 1155, 1157, and 1213, is called the SNMP version 1 (SNMPv1) framework. Relevant portions of the proposed framework for version 2C of the Simple Network Management Protocol (SNMPv2C) are described in RFCs 1901 through 1908.

The WinSNMP API supports the SNMP protocol functionality described in the relevant Internet RFCs. WinSNMP places no constraints on the use of SNMPv1 or SNMPv2C by WinSNMP applications.

A management entity can support a different version of SNMP than the one the WinSNMP application supports. The Microsoft WinSNMP implementation performs the appropriate translations from SNMPv1 to SNMPv2C in accordance with the relevant RFC.


RFCs Relevant to WinSNMP

TCP/IP standards are defined in Requests for Comments (RFCs), which are published by the Internet Engineering Task Force (IETF). The RFCs that are relevant to WinSNMP features are listed in the following table.

RFC number | Title
1155 | "Structure and Identification of Management Information for TCP/IP-based Internets"
1157 | "A Simple Network Management Protocol (SNMP)"
1213 | "Management Information Base for Network Management of TCP/IP-based internets: MIB-II"
1901 | "Introduction to Community-based SNMPv2"
1902 | "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1903 | "Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1904 | "Conformance Statements for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1905 | "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1906 | "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1907 | "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)"
1908 | "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework"
2089 | "V2ToV1 Mapping SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent"


Software Requirements for the WinSNMP API

A WinSNMP application must access the WinSNMP API through the dynamic-link library WSNMP32.DLL.

The following files are required to support the functionality of the WinSNMP API.

Filename | Description
WSNMP32.LIB | WinSNMP Library
WSNMP32.DLL | Provides WinSNMP interface
WINSNMP.H | WinSNMP header file
SNMPTRAP.EXE | Receives SNMP traps and forwards them to MGMTAPI.DLL, the Microsoft SNMP Manager API library
SNMPAPI.DLL | Provides SNMP utilities


The WinSNMP Model

The WinSNMP-compliant model includes the following basic components:

  • A WinSNMP-enabled SNMP network management application, that is, a WinSNMP-compliant application
  • The WinSNMP function layer
  • A WinSNMP-enabled SNMP service provider, that is, a WinSNMP-compliant implementation

Network management applications that must convey SNMP messages operate efficiently in an event-driven environment. This is because SNMP is a datagram-based or connectionless protocol between remote entities that do not establish virtual circuits.

Since Microsoft Windows applications are also event-driven, WinSNMP uses a programming model in which the receipt and processing of asynchronous message-events drive management applications. An asynchronous message-event can be an SNMP operation request by a manager application, or the response to a request by an agent application.

SNMP sends requests and responses as SNMP messages. An SNMP message is an SNMP protocol data unit (PDU) plus additional message header elements defined by the relevant RFC. For more information, see About SNMP Messages, Working with Variable Binding Lists and Working with Protocol Data Units.


About the Microsoft WinSNMP Implementation

The Microsoft WinSNMP implementation complies with WinSNMP version 2.0. It supports all the functions and operations defined in both the WinSNMP version 1.1a specification and the WinSNMP version 2.0 Addendum. The implementation provides the following services for WinSNMP applications:

  • Manages communications to and from management entities. The entity can reside on the local computer or be connected through a local or wide-area network, or the Internet. For more information, see Levels of SNMP Support.
  • Hides the details of SNMP protocol, Abstract Syntax Notation One (ASN.1), and the Basic Encoding Rules (BER) for describing transfer syntax.
  • Verifies the correctness of PDUs and rejects invalid PDUs. For more information, see Working with Protocol Data Units.
  • Transforms SNMPv2C PDU types when necessary in accordance with the relevant RFCs.
  • Converts SNMPv1 traps from an SNMPv1 agent to SNMPv2C traps in accordance with RFC 1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework." For more information, see Translating Traps from SNMPv1 to SNMPv2C.
  • Supports the application's retransmission policy and provides retransmission execution support. For more information, see The WinSNMP Database and About Retransmission.
  • Provides entity and context translation support for the application. For more information, see The WinSNMP Database and Setting the Entity and Context Translation Mode.

For additioinal information about the relationship between a WinSNMP application and the implementation, see WinSNMP Data Management Concepts and WinSNMP Sessions.


The WinSNMP Database

The Microsoft WinSNMP implementation maintains a store of administrative information in a database. The database includes the following information:

  • Network and version properties. The implementation uses these properties to determine which network transport protocol and SNMP version framework to use to complete transmission requests. For more information, see About SNMP Versions.
  • Entity and context translation mode. The implementation uses this mode to interpret user-friendly names for SNMP entities and contexts. For more information, see Setting the Entity and Context Translation Mode.
  • Retransmission policy setting. The implementation uses this setting to determine whether or not it should execute the application's retransmission policy. The implementation stores a time-out value and a retry count for each destination entity. For more information, see About Retransmission and Managing the Retransmission Policy.


Levels of SNMP Support

The Microsoft WinSNMP implementation provides level 2 SNMP communications support. Level 2 supports the Internet Engineering Task Force (IETF) standard SNMPv2 protocol as defined in RFCs 1902-1908. It also supports the community-based message wrapper as defined in RFC 1901 (SNMPv2C).

Level 2 communications support includes message encoding and decoding services, previously called Level 0 communications support in WinSNMP version 1.1a. Level 2 also supports all SNMPv1 protocol operations, previously called Level 1 communications support in WinSNMP version 1.1a.

The implementation returns the maximum level of SNMP communications it supports in response to a call by the WinSNMP application to the SnmpStartup function.

If the WinSNMP application uses the implementation for SNMP message encoding and decoding only, the application must perform required transformations that the implementation would have performed. This includes translating SNMPv1 traps returned by a call to the SnmpRecvMsg function, to SNMPv2C traps. It also includes translating PDU types defined by SNMPv1 to the relevant PDU type defined by SNMPv2C, in accordance with RFC 1908.


WinSNMP Sessions

A session is the basic unit of resource and communications management between a calling WinSNMP application and the Microsoft WinSNMP implementation. It is recommended that an application use sessions to organize its operations and reduce the demand on the implementation's resources.

For more information, see Opening and Closing a WinSNMP Session.


WinSNMP Data Management Concepts

The topics in this section cover the major concepts of data management that apply to programming with the WinSNMP API.

  • Object identifiers
  • WinSNMP Descriptors
  • Resource handle objects
  • C-style strings
  • Allocating WinSNMP memory objects


Object Identifiers

An SNMP object identifier uniquely names an object and identifies its location within a Management Information Base (MIB) tree structure. Object identifiers are application-independent Abstract Syntax Notation One (ASN.1) data types that consist of a sequence of non-negative integers, or subidentifiers. Object identifiers must have a minimum of two subidentifiers and they must not exceed 128 subidentifiers.

The WinSNMP programming environment uses the smiOID structure to manage object identifiers. The format of the object identifier array in an smiOID structure is one subidentifier per array element.

The dotted numeric string representation of an object identifier separates its subidentifiers with periods; for example, "1.2.3.4.5.6".

For more information, see The SNMP Management Information Base (MIB) and the relevant RFCs.


WinSNMP Descriptors

In the WinSNMP programming environment a descriptor is one of the following two structures:

  • An smiOCTETS structure which describes an octet string variable
  • An smiOID structure which describes an SNMP object identifier variable

A WinSNMP descriptor is a structure that has two members: a length member, len, and a pointer member, ptr. The ptr member points to the octet string or object identifier of interest. The ptr member can be either the smiLPBYTE or smiLPUINT32 data type.

An smiOCTETS descriptor or an smiOID descriptor can be the value member of an smiVALUE structure. The smiVALUE structure describes the value associated with a variable name in a variable binding entry.

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS and smiOID structures. Therefore, the application must call the SnmpFreeDescriptor function to free the memory for the ptr member of these structures.

String members in descriptors do not require a NULL terminating byte. For additional information about managing the memory allocated for descriptors, see Allocating WinSNMP Memory Objects.


Resource Handle Objects

The structure of a resource object is restricted to the Microsoft WinSNMP implementation. A WinSNMP application can access a resource object with a handle.

The implementation can allocate one of the following types of resource handles for a WinSNMP application.

Handle type | Description
HSNMP_SESSION | Handle to a WinSNMP session
HSNMP_ENTITY | Handle to an SNMP entity
HSNMP_CONTEXT | Handle to a WinSNMP context
HSNMP_PDU | Handle to a protocol data unit
HSNMP_VBL | Handle to a variable binding list

A WinSNMP application can request that the implementation create or delete resource handles, but the implementation performs the operation. For additional information about freeing individual resources, see the SnmpFreeDescriptor, SnmpFreeVbl, SnmpFreePdu, SnmpFreeEntity, and SnmpFreeContext functions.


C-Style Strings

A WinSNMP application can use NULL-terminated C-style strings to convert entity and object identifier (OID) objects to and from their string representations.

The WinSNMP functions that manipulate C-style strings include SnmpStrToEntity, SnmpEntityToStr, SnmpStrToOid, and SnmpOidToStr. Because SnmpEntityToStr and SnmpOidToStr return a pointer to a C-style string variable, the WinSNMP application must pass an appropriate value in the size parameter when it makes calls to these functions.

Note The context parameter of the SnmpStrToContext and SnmpContextToStr functions must be an octet string structure, that is, an smiOCTETS structure. The context parameter cannot be a C-style string. The string contained in an smiOCTETS structure does not require a NULL-terminating byte.


Allocating WinSNMP Memory Objects

Descriptors, resource handles and C-style strings are the three types of memory objects in the WinSNMP programming environment.

The type of object determines whether the Microsoft WinSNMP implementation or the WinSNMP application allocates and deallocates the memory for the object. This reduces unnecessary allocation of temporary buffer space and unnecessary copying of buffers.

The following table summarizes the allocation and deallocation of resources for WinSNMP memory objects.

Object type | Description
smiOID or smiOCTETS descriptor | If the WinSNMP application allocates the memory, it must deallocate the memory with a call to an appropriate function. If the implementation allocates the memory, the application must call the SnmpFreeDescriptor function to deallocate the memory.
smiVALUE structure | If the value member is an smiOID or an smiOCTETS descriptor, the application must proceed as indicated above for descriptors.
Resource handle | The implementation allocates, manages, and frees the memory.
C-style string | The WinSNMP application must manage and free the memory it allocates.

For more information, see Freeing WinSNMP Descriptors.


WinSNMP Communications Management Concepts

The WinSNMP API provides network transport independence for SNMP-based network management applications that execute in the Microsoft Windows® 2000 operating environment. The topics in this section cover concepts of communications management that apply to programming with WinSNMP.

  • About SNMP Messages
  • About Traps and Notifications
  • About Retransmission


About SNMP Messages

The Simple Network Management Protocol uses messages to communicate and exchange information between remote SNMP entities. SNMP messages contain protocol data units (PDUs) plus additional message header elements defined by the relevant RFC. A PDU is a data packet that contains SNMP data components (or fields).

The format of an SNMP message is the same for both SNMPv1 and SNMPv2C. However, SNMPv2C supports additional PDU types. For example, it supports the SNMP_PDU_GETBULK request type, which enables an application to efficiently retrieve large blocks of data from target entities.


Translating Message Requests

If a WinSNMP application requests functionality that is available under the SNMP version 2C framework (SNMPv2C), but the target entity supports only the SNMP version 1 framework (SNMPv1), the Microsoft WinSNMP implementation attempts to translate the request to the SNMPv1 format. To do this, the implementation uses the procedures defined in RFC 1908, "Coexistence Between Version 1 and Version 2 of the Internet-Standard Network Management Framework." If translation is not possible, the SnmpSendMsg function fails with the extended error code SNMPAPI_OPERATION_INVALID.


About Traps and Notifications

One type of message an SNMP agent application can send to a WinSNMP application is an asynchronous message that informs the application of a significant event. An example of a significant event is when a network link shuts down or when an authentication failure occurs.

These types of messages are called traps under SNMPv1 and notifications under SNMPv2C. The Microsoft WinSNMP implementation always translates SNMPv1 traps to the SNMPv2C format, as defined by RFC 1908.

When you call the SnmpCreatePdu function to create a trap PDU, you can create only an SNMPv2C trap PDU. The only type of trap PDU you can update with a call to the SnmpSetPduData function is an SNMPv2C trap PDU.

For more information, see the following topics:

  • Translating Traps from SNMPv1 to SNMPv2C
  • Trap Formats


Translating Traps from SNMPv1 to SNMPv2C

When the Microsoft WinSNMP implementation receives traps from an entity operating under the SNMPv1 framework, it translates the traps to the SNMPv2C format. Therefore, when SnmpRecvMsg delivers a trap it is always in the SNMPv2C format. RFC 1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework," specifies the rules for translating from the SNMPv1 to the SNMPv2C trap format.

A WinSNMP application can check the last variable binding entry in a variable binding list to determine if the entry is a trap translated from the SNMPv1 to the SNMPv2C format. If so, the last variable binding will always be equal to the value "snmpTrapEnterpriseOID.0".

For more information, see Managing Traps and Notifications.


Trap Formats

The format of trap PDUs is different than that of other PDUs. The format of SNMPv1 traps and SNMPv2C traps is also different.

Under the SNMPv2C framework, the PDU trap format is a variable binding list of n variable binding entries organized in the following manner:

  • The first variable binding entry contains a time-stamp.
  • The second variable binding entry is an object identifier that identifies the trap.
  • The third through n variable binding entries, if present, contain additional information associated with the trap.

Under the SNMPv1 framework, the PDU trap format is as follows.

Field | Description
enterprise | Identifies the type of device that generated the trap
agent-addr | Identifies the IP address of the device that generated the trap
generic-trap/specific-trap | Identifies a predefined trap type
time-stamp | Identifies when the trap was generated
variable-bindings | Contains additional information associated with the trap

The SnmpRecvMsg function always returns a message in the SNMPv2C format. If the message contains the operation type SNMP_PDU_TRAP, the application can read the variable binding entries of the message and retrieve the information associated with the trap.


About Retransmission

A WinSNMP application can make SNMP operation requests in various ways. The application can issue several requests to an SNMP agent, without waiting for a response, or it can issue a single request and wait for the response. Since SNMP can be implemented on multiple transport protocols, delivery mechanisms and reliability characteristics can vary.

When you code the WinSNMP application you must determine the level of reliability you need for communications operations, based on the way the application issues operation requests. Then you must select a retransmission strategy and implement a retransmission policy.

A retransmission policy includes a time-out period and a retry count. A time-out period is the elapsed time, in hundredths of a second, between an application's issuance of an SnmpSendMsg request and its receipt of the corresponding message. The application receives the message as a result of a call to the SnmpRecvMsg function. The time-out value is the period of time the Microsoft WinSNMP implementation waits for an entity to respond to a communication request. If there is no response within the time-out period, the implementation either retransmits the request if the retry count value specifies retransmission attempts, or it fails the call to SnmpSendMsg. A retry count is the maximum number of retransmission attempts the implementation makes if an SNMP transmission request fails.

The implementation stores time-out values and retry counts in its database for the application. The implementation stores individual values for each destination entity.

Applications must establish their own polling frequencies and they must manage timer variables. For more information, see Managing the Retransmission Policy.


WinSNMP Programming Tasks

The following table summarizes the basic programming procedures that you must perform to code a WinSNMP application, and the topics that provide information about these tasks.

Programming task | Task-related function and topics
Open the WinSNMP application. | Use SnmpStartup. See Opening and Closing a WinSNMP Application.
Open one or more WinSNMP sessions. | Use SnmpCreateSession. See Opening and Closing a WinSNMP Session.
Register to receive traps or notifications. | Use SnmpRegister. See Managing Traps and Notifications.
Create one or more variable binding lists for incorporation in a PDU. | Use SnmpCreateVbl, SnmpDuplicateVbl, SnmpSetVb. See Working with Variable Binding Lists. Note: The application may need to call other variable binding functions to create the variable binding list.
Create one or more PDUs for transmission and processing. | Use SnmpCreatePDU, SnmpSetPduData, SnmpDuplicatePDU. See Working with Protocol Data Units. Note: The application may need to call other PDU functions and WinSNMP utility functions to create the PDU.
Submit one or more SNMP operation requests. | Use SnmpSendMsg. See Sending SNMP Messages.
Retrieve the response to the SNMP operation request. | Use SnmpRecvMsg. See Receiving SNMP Messages.
Process the request response. | Use application-specific logic.
Close each WinSNMP session. | Use SnmpClose. See Opening and Closing a WinSNMP Session.
Close the WinSNMP application. | Use SnmpCleanup. See Opening and Closing a WinSNMP Application.

The following topics contain additional information about other general programming concepts specific to the WinSNMP environment.

General programming tasks Managing Object Identifiers

Freeing WinSNMP Descriptors

Setting the Entity and Context Translation Mode

Managing the Retransmission Policy

Writing WinSNMP Applications with Multiple Threads

Registering an SNMP Agent Application

In addition, the WinSNMP application may need to incorporate calls to the following WinSNMP functions: SnmpFreeVbl, SnmpFreeEntity, SnmpFreeDescriptor, SnmpFreeContext, and SnmpFreePdu. This enables the Microsoft WinSNMP implementation to free WinSNMP memory objects. As a general rule, the WinSNMP application should free all resources allocated as the result of a call to a WinSNMP function. For additional information about deallocating resources, see Allocating WinSNMP Memory Objects.


Opening and Closing a WinSNMP Application

The WinSNMP application must call the SnmpStartup function successfully before it calls any other WinSNMP function. The SnmpStartup function enables the Microsoft WinSNMP implementation to perform initialization procedures. The function also returns to the application the version of the WinSNMP API that the implementation supports, the level of SNMP communications it supports, and the implementation's default translation and retransmission modes.

The WinSNMP application must call the SnmpCleanup function when the application no longer requires the implementation's services. Even though SnmpCleanup enables the implementation to deallocate all resources allocated to the application, it is recommended that the application first call the SnmpClose function once for each open WinSNMP session, to maximize the implementation's performance. The WinSNMP application must call SnmpCleanup as the last WinSNMP function before it terminates.


Opening and Closing a WinSNMP Session

To open a session, an application calls the SnmpCreateSession function. If the function completes successfully, the Microsoft WinSNMP implementation opens a session, and the function returns a session identifier in the form of an HSNMP_SESSION handle. All WinSNMP functions that return handle variables include the session identifier as an input parameter. This enables the implementation to use the handle to efficiently manage resources at the session level.

An application can have multiple sessions open at one time. Multiple sessions within an application can share handle variables.

If the implementation cannot open a session because of resource limitations, it returns SNMPAPI_FAILURE when the application calls SnmpCreateSession. If the application then calls the SnmpGetLastError function, it returns SNMPAPI_ALLOC_ERROR.

A call to the SnmpClose function enables the implementation to free any remaining resources and to close the session.

For more information, see Resource Handle Objects and WinSNMP Sessions.


Managing Traps and Notifications

The WinSNMP application must register to receive traps and notifications by calling the SnmpRegister function with SNMPAPI_ON. The application can unregister and disable traps and notifications by calling the function with SNMPAPI_OFF.

Several options are available when the application calls SnmpRegister. The application can register or unregister for the following traps and notifications:

  • One type of trap or notification
  • All traps and notifications
  • All sources of trap and notification requests
  • Traps and notifications from all management entities
  • Traps and notifications for every context

To register and receive a predefined trap or notification type, the application must define an object identifier (an smiOID structure) for each predefined type. The structure must contain a pattern-matching sequence for the type of trap or notification. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," defines trap and notification object identifiers.

To retrieve outstanding trap data and notifications for a WinSNMP session, a WinSNMP application must call the SnmpRecvMsg function with the session handle returned by the SnmpCreateSession function.

For more information, see Sending SNMP Messages and Receiving SNMP Messages. For additional information about allocation and deallocation of resources for traps and notifications, see Allocating WinSNMP Memory Objects.


Multiple Trap Registrations

Several options are available when a WinSNMP application registers a WinSNMP session for traps or notifications. Because of this, an application can call the SnmpRegister function multiple times, in effect defining a custom filter for the reception of traps and notifications. For example, you can register for one type of trap or notification, or for all traps and notifications, depending on the value of the notification parameter. Additionally, the application can specify values in other parameters to the SnmpRegister function to further define the traps and notifications that should reach an application. For more information, see Managing Traps and Notifications.

Following are instances in which multiple calls to SnmpRegister are redundant. In these instances SnmpRegister returns SNMPAPI_SUCCESS if the function completes successfully, but the redundant registration is ineffective.

  1. A call to the SnmpRegister function requesting filtered delivery of traps and notifications to the session, after a previous call to SnmpRegister requesting delivery of all traps and notifications (unfiltered delivery). This call is redundant because the session is already receiving all traps and notifications, including the single type defined by the filter.
  2. A duplicate call to SnmpRegister, or one in which the parameter list is identical to the parameter list in a previous call to SnmpRegister for the session.
  3. A call to the SnmpRegister function requesting filtered delivery of traps and notifications based on an object identifier (OID) whose prefix is an OID specified in a previous call to SnmpRegister. For example, you can specify "1.3.6.1.4.1.311" in the notification parameter to receive notifications originating from any Microsoft SNMP agent entity. If you call SnmpRegister again and specify "1.3.6.1.4.1.311.1", the second call is redundant because the session is already receiving all traps and notifications that contain the OID prefix "1.3.6.1.4.1.311".

To unregister the session, you must match each unique registration call to the SnmpRegister function. Call SnmpRegister to unregister the session, and ensure that the first five parameters to SnmpRegister are identical to those in the initial registration call. The only difference between the initial call and the unregistering call is that when registering you must specify the value SNMPAPI_ON in the status parameter, and when you call the function to unregister, you must specify SNMPAPI_OFF. You do not need to match redundant registration calls to the SnmpRegister function. You need only match the first unique registration call.

To change filtering criteria, it may be necessary for an application to first unregister and disable delivery of certain traps or notifications. Then the application can create a new filter by calling SnmpRegister, passing appropriate values.


Working with Variable Binding Lists

A variable binding is the pairing of an SNMP object instance name with an associated value. A variable binding list is a series of variable binding entries. In the WinSNMP programming environment, a protocol data unit (PDU) includes a variable binding list.

The details of the variable binding list structure are restricted to the Microsoft WinSNMP implementation. A WinSNMP application can access a variable binding list with a handle of the type HSNMP_VBL. For more information, see Resource Handle Objects.

The WinSNMP application can construct and manipulate variable binding lists, and include them in PDUs. To perform these operations, the application uses the WinSNMP variable binding functions. For additional information about working with WinSNMP and variable binding lists, see the following topics:

  • Creating a Variable Binding List
  • Managing a Variable Binding List

For additional information about variable bindings and variable binding lists, see RFC1905, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)," and the WinSNMP Variable Binding Functions.


Creating a Variable Binding List

The SnmpCreateVbl function creates a new variable binding list. If the WinSNMP application specifies a variable name and a value, the function creates the list and adds the name and value as the first entry in the list. If the application specifies NULL for the variable name, the function creates an empty list.

To copy a variable binding list, call the SnmpDuplicateVbl function. The function creates a new variable binding list and initializes the new list with a copy of the data in the source variable binding list.

The SnmpCreateVbl function and the SnmpDuplicateVbl function allocate any necessary memory for the new variable binding list. The WinSNMP application must release the resources associated with these lists. It is recommended that the application do this by matching each call to SnmpCreateVbl and SnmpDuplicateVbl with a corresponding call to the SnmpFreeVbl function when it is appropriate to free the allocated memory.


Managing a Variable Binding List

The SnmpGetVb function retrieves variable binding information from a variable binding list. The function retrieves the variable name and the variable's associated value from the variable binding entry specified by the WinSNMP application.

To update variable binding entries in a variable binding list, call the SnmpSetVb function. The SnmpSetVb function also appends new variable binding entries to an existing variable binding list.

The WinSNMP application must call the SnmpDeleteVb function to remove entries from a variable binding list.

To retrieve, modify or delete a variable binding entry, the WinSNMP application must specify the position of the entry in the variable binding list.

A call to the SnmpSetPduData function associates a variable binding list with a PDU. A call to the SnmpGetPduData function retrieves a variable binding list from a PDU. An individual variable binding is not directly associated with a PDU, but it is indirectly associated through its inclusion in a variable binding list.


Working with Protocol Data Units

The Simple Network Management Protocol sends operation requests and responses as SNMP messages. An SNMP message is an SNMP protocol data unit (PDU) plus additional message header elements defined by the relevant RFC. A PDU includes a variable binding list.

The structure of a PDU is restricted to the Microsoft WinSNMP implementation. A WinSNMP application can access a PDU with a handle of the type HSNMP_PDU. The WinSNMP application must create a PDU before it calls the SnmpSendMsg function or the SnmpEncodeMsg function.

The application can extract and update the data elements of a PDU, and release resources allocated for PDUs. To perform these operations, the application uses the WinSNMP PDU functions. For additional information about working with PDUs in the WinSNMP programming environment, see the following topics:

  • Creating a PDU
  • Updating a PDU
  • Duplicating a PDU
  • Validating a PDU
  • Matching Response and Request PDUs

For more information, see Working with Variable Binding Lists and Resource Handle Objects.


Creating a PDU

To create and initialize a PDU a WinSNMP application calls the SnmpCreatePdu function. The application must call SnmpCreatePdu before it calls the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit a PDU. The application must also call SnmpCreatePdu before it calls the SnmpEncodeMsg function to request encoding of an SNMP message.

The application must call the SnmpFreePdu function to release the resources that the SnmpCreatePdu function allocates for new PDUs.


Updating a PDU

A WinSNMP application can retrieve and update selected PDU fields by using the SnmpGetPduData and the SnmpSetPduData functions.

The application can retrieve the PDU type, request identifier, error status, and error index fields from a specific PDU. It can also retrieve the handle to the variable binding list. The application can update the PDU_type and request_id fields.

If the PDU type is equal to SNMP_PDU_GETBULK, the application can also update the non_repeaters and the max_repetitions fields of the PDU.


Duplicating a PDU

The SnmpDuplicatePdu function duplicates a PDU, allocating any necessary memory. To release resources allocated by SnmpDuplicatePdu for a new PDU, a WinSNMP application must call the SnmpFreePdu function.


Validating a PDU

When the WinSNMP application calls the SnmpSendMsg function or the SnmpEncodeMsg function, the Microsoft WinSNMP implementation verifies the validity of the PDU and the other function parameters.

The value of one PDU data component (or field) can be valid individually, but it may be invalid in combination with values for other fields. For example, unless the PDU_type field of the PDU is SNMP_PDU_GETBULK or SNMP_PDU_RESPONSE, both the error_status and error_index fields must be equal to zero. Any other value combination constitutes an invalid PDU.

The implementation rejects invalid PDUs and returns the error status SNMPAPI_FAILURE. It sets an extended error code equal to SNMPAPI_PDU_INVALID.


Matching Response and Request PDUs

The order in which the WinSNMP application receives SNMP responses may not match the order in which the application submits SNMP operation requests. To match the response with the request, the application must use the request identifier field (the request_id) of the response.

The request_id field is a unique numeric value that identifies the PDU. Applications can assign request identifiers by calling the SnmpCreatePdu function or the SnmpSetPduData function. Call the SnmpGetPduData function to retrieve a PDU's request_id.


Assigning Request Identifiers

A WinSNMP application can call the SnmpCreatePdu function or the SnmpSetPduData function to assign an application-generated request identifier to a PDU. The application must pass the value in the request_id parameter.

An application can request that the Microsoft WinSNMP implementation generate and assign a request identifier to a PDU by passing zero in the request_id parameter of the SnmpCreatePdu function. The application can retrieve the assigned request identifier with a call to the SnmpGetPduData function.

To assign a request identifier equal to a specific value, including zero, the application must pass that value in the request_id parameter of the SnmpSetPduData function.

When the implementation executes the application's retransmission policy, it includes the request_id field of the original PDU in each retransmitted SNMP message. For more information, see About Retransmission and Managing the Retransmission Policy.

Note When the implementation receives traps from an SNMPv1 entity, it assigns a non-zero value to the request_id field of the PDU. This value may duplicate a request identifier used by the application in a request PDU. Applications must check for duplication.


Sending SNMP Messages

A WinSNMP application initiates a transmission request by sending an SNMP message. SNMP messages include an SNMP protocol data unit. For more information, see Working with Protocol Data Units.

A WinSNMP application must call the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit the PDU, with the other required message elements defined by the relevant RFC. In addition to the destination entity, the application must specify the source entity and a context for the request. The SnmpSendMsg function executes asynchronously.

The WinSNMP application must call the SnmpRecvMsg function to retrieve the response to an SnmpSendMsg request.

The implementation verifies the validity of the PDU and the other message elements when an application calls SnmpSendMsg.


Receiving SNMP Messages

The WinSNMP application must call the SnmpRecvMsg function to retrieve the response to an SnmpSendMsg request.

The SnmpCreateSession function passes an application window handle and a notification message identifier to the Microsoft WinSNMP implementation. When the application window receives this message, it signals the application to call the SnmpRecvMsg function using the session handle returned by SnmpCreateSession.

The SnmpRecvMsg function returns two entity handles, a context handle, and the handle to a PDU. It is recommended that the WinSNMP application free these resources using the SnmpFreeEntity, SnmpFreeContext, and SnmpFreePdu functions.

For additional information about managing the time between a call to the SnmpSendMsg function and the receipt of the corresponding response, see About Retransmission. For additional information about using the request_id PDU field to match a response PDU with its request PDU, see Matching Response and Request PDUs.


General WinSNMP Programming Tasks

The following topics contain information about general programming concepts specific to the WinSNMP environment.

  • Managing Object Identifiers
  • Freeing WinSNMP Descriptors
  • Setting the Entity and Context Translation Mode
  • Managing the Retransmission Policy
  • Writing WinSNMP Applications with Multiple Threads
  • Registering an SNMP Agent Application


Managing Object Identifiers

The WinSNMP API provides several WinSNMP utility functions that simplify the manipulation of object identifiers for WinSNMP applications.

The SnmpOidToStr function converts the internal binary representation of an object identifier to its dotted numeric string format. When you call SnmpOidToStr, specify a string buffer of MAXOBJIDSTRSIZE length (1408 bytes) to ensure that the output buffer is large enough to hold the converted string. To convert an object identifier from the dotted numeric string format to its internal binary representation, call the SnmpStrToOid function.

To copy an SNMP object identifier call the SnmpOidCopy function. This function allocates any necessary memory for the new object identifier.

A WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure specified by both the SnmpStrToOid and the SnmpOidCopy functions.

The SnmpOidCompare function compares two SNMP object identifiers. The WinSNMP application can specify the number of subidentifiers to compare. Call SnmpOidCompare to determine whether two object identifiers have common prefixes.

For additional information about managing the memory allocated for object identifiers, see Allocating WinSNMP Memory Objects.


Freeing WinSNMP Descriptors

The WinSNMP programming environment assigns the deallocation of descriptor resources to the WinSNMP implementation or the WinSNMP application, depending on which component allocates the memory for the descriptor.

To free the resources for an smiOID or an smiOCTETS descriptor, the following rules apply:

  • For input parameters

    Because the WinSNMP application allocates the memory for input objects with variable lengths, the application must free that memory using an appropriate function. For example, if the application allocated the resources with a call to the GlobalAlloc function, it should use the GlobalFree function to deallocate the resources. If the application allocated the resources with a call to the HeapAlloc function, it should call the HeapFree function.

  • For output parameters

    A call to any of the following functions results in the implementation allocating memory for an smiOID or an smiOCTETS descriptor: SnmpGetVb, SnmpEncodeMsg, SnmpOidCopy, SnmpContextToStr, and SnmpStrToOid.

    Because the implementation allocates the memory for these output objects, the application must call the SnmpFreeDescriptor function to deallocate the resources. This function enables the implementation to free the memory allocated for the ptr member of these structures.

To free the resources for an smiVALUE structure, the following rules apply:

A WinSNMP application must check the syntax member of an smiVALUE structure to correctly evaluate the value member of the structure. If the syntax member indicates that the value member is an smiOCTETS or an smiOID descriptor, and the implementation allocated the resources for the descriptor, the application must call SnmpFreeDescriptor. This enables the implementation to free the memory. If the application allocated the resources, it must free the memory using an appropriate function, as indicated earlier.

For more information, see Allocating WinSNMP Memory Objects.


Setting the Entity and Context Translation Mode

The WinSNMP application can specify the interpretation and translation of entity and context parameters by setting the entity and context translation mode. The Microsoft WinSNMP implementation stores the mode in a database.

The setting of the entity and context translation mode determines the manner in which the SnmpStrToEntity function and the SnmpStrToContext function interpret input strings. The setting also determines the type of output string that the SnmpEntityToStr and the SnmpContextToStr functions return. For more information, see Support for IPX Address Strings in WinSNMP.

The implementation returns the current default entity and context translation mode in the nTranslateMode parameter of the SnmpStartup function. To retrieve the current entity and context translation mode in effect for the implementation, an application can call the SnmpGetTranslateMode function at any time.

The valid entity and context translation modes follow.

Mode | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as literal SNMP transport addresses, and context parameters as literal SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of zero in the version field.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as literal SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of 1 in the version field.

The implementation tries to associate resources in its database with the literal transport address of the management entity.

To change the entity and context translation mode setting a WinSNMP application must call the SnmpSetTranslateMode function. If the requested translation mode is invalid, the function fails, and SnmpGetLastError returns the error code SNMPAPI_MODE_INVALID.


Support for IPX Address Strings in WinSNMP

WinSNMP 2.0 formalizes the use of IPX address strings. If you specify an IPX address string as an input parameter to the SnmpStrToEntity function, you must format the string using the following standards:

  • A network number that consists of eight hexadecimal digits (zero-filled if necessary)
  • A separator (either ":", "." or " – ")
  • A node number that consists of 12 hexadecimal digits (zero-filled if necessary)

For example, 00000001:00081A0D01C2 or 00000001.00081a0d01c2. Hexadecimal digits can be uppercase or lowercase.

This is the format the SnmpEntityToStr function uses to return an IPX address string. The string is returned when an application that is operating in one of the SNMPAPI_UNTRANSLATED modes calls the SnmpEntityToStr function. The string can also be returned when the application is operating in SNMPAPI_TRANSLATED mode and no user-friendly name is available for the entity.


Managing the Retransmission Policy

The WinSNMP application can request that the Microsoft WinSNMP implementation execute the application's retransmission policy. When the implementation manages retransmission, it uses the time-out period and the retry count values in its database.

The implementation identifies the default retransmission mode in a return value from the SnmpStartup function during initialization. The mode can be one of the following values.

Value | Meaning
SNMPAPI_ON | The implementation is executing the application's retransmission policy.
SNMPAPI_OFF | The implementation is not executing the application's retransmission policy.

A WinSNMP application can retrieve at any time the current retransmission mode in effect for the implementation by calling the SnmpGetRetransmitMode function. The WinSNMP API provides other database functions that simplify management of the retransmission policy.

At any time during program execution, the WinSNMP application can adjust execution of the policy by performing one of the following steps:

  • Request that the implementation start or stop executing the retransmission policy by calling the SnmpSetRetransmitMode function. For more information, see Turning Retransmission On and Off.
  • Modify the time-out period and retry count values in the implementation's database. For more information, see Changing the Retransmission Policy.
  • Call the the SnmpCancelMsg function to cancel the retransmission cycle and release internal data structures associated with a single SNMP message request. For more information, see Canceling Retransmission.

The application can execute its own retransmission policy. In this case, execution may or may not be based on the values in the database.


Turning Retransmission On and Off

An application can set the retransmission mode with a call to the SnmpSetRetransmitMode function. The new retransmission mode applies to subsequent calls to the SnmpSendMsg function.

When the application calls SnmpSetRetransmitMode with the retransmission mode value SNMPAPI_ON, the Microsoft WinSNMP implementation begins execution of the application's retransmission policy. The new retransmission mode does not affect outstanding SNMP messages. An outstanding message is one that has no response at the time the application changes the retransmission mode.

When the WinSNMP application calls the SnmpSetRetransmitMode function with the retransmission mode value SNMPAPI_OFF, the implementation stops executing the retransmission policy. The implementation cancels retransmission attempts for outstanding SNMP messages. This is because it may not be possible for the implementation to handle all outstanding SNMP requests and operations plus new requests, before an application time-out or retry counter signals an event.


Canceling Retransmission

If there is no response to a communication request within the time-out period specified for a destination entity, and if retransmissions are specified for the entity, the Microsoft WinSNMP implementation retransmits the request. A call to the SnmpCancelMsg function can cancel this retransmission cycle and release internal data structures associated with the message request.

Note that it is possible for a destination entity to receive an SNMP message that has been cancelled by a call to the SnmpCancelMsg function. It is also possible that a destination entity can respond to a cancelled SNMP message. This is because transaction queuing occurs at multiple levels. However, once a message has been cancelled by a call to SnmpCancelMsg, the Microsoft WinSNMP implementation will not retransmit the message, submit a response PDU, or send a time-out notification to the application for that message.


Changing the Retransmission Policy

The Microsoft WinSNMP implementation provides retransmission policy support by storing a time-out value and a retry count for the WinSNMP application in a database. The implementation stores values for individual destination entities. The implementation initially supplies default values for these elements, but an application can add or modify values for individual entities.

A call to the SnmpGetTimeout and SnmpGetRetry functions returns the time-out and retry count values for a specific destination entity. To change the time-out value, a WinSNMP application must call the SnmpSetTimeout function. To change the retry count value the application must call the SnmpSetRetry function. The updated settings affect new SNMP message requests to the destination entity.


Writing WinSNMP Applications with Multiple Threads

The Microsoft WinSNMP implementation ensures that the WinSNMP operations of one process do not modify the WinSNMP settings of another process.

A WinSNMP application with multiple threads must ensure that WinSNMP operations that set application-level parameters are thread-safe. The functions that set application-level parameters are SnmpSetTranslateMode and SnmpSetRetransmitMode. These functions modify settings for the entity and context translation mode and the retransmission mode.

For more information, see Multiple Threads.


Registering an SNMP Agent Application

In addition to SNMP manager operations, the WinSNMP API version 2.0 also supports SNMP agent operations.

To register a WinSNMP application as an SNMP agent, the application can call the SnmpListen function. This function informs the Microsoft WinSNMP implementation that an SNMP entity will be acting in the role of an SNMP agent. The application can also call SnmpListen to inform the implementation when it will no longer be acting as an agent.

If an application calls the SnmpListen function and passes the value SNMPAPI_ON in the lStatus parameter, the following actions occur:

  1. The entity that will be functioning in an SNMP agent role binds to its assigned port, and "listens" for incoming SNMP message requests.
  2. The agent uses application-specific logic to process each SNMP request.
  3. The agent forms appropriate responses to each request.
  4. The agent transmits the response to the requesting entity by calling the SnmpSendMsg function. When the agent calls SnmpSendMsg, it specifies the address of the agent in the srcEntity parameter, and the address of the remote manager entity in the dstEntity parameter. (These values are the reverse of the values the agent entity received in these parameters when it called the SnmpRecvMsg function to retrieve an SNMP request.)

For more information about SNMP management applications and agent applications, see About SNMP.


WinSNMP API Reference

The following sections describe in detail the functions, structures, data types, function return values, and common error codes of the WinSNMP API.

  • WinSNMP Data Types
  • WinSNMP Common Error Codes
  • WinSNMP Function Return Values
  • WinSNMP Functions
  • WinSNMP Structures


WinSNMP Data Types

The standard WinSNMP data types are defined in the WINSNMP.H file.

Note that WinSNMP specifies some parameters with the signed long integer type, smiINT. This enables WinSNMP to comply with the data elements, especially the PDU components, defined in the relevant RFCs.


WinSNMP Error Codes

Note The errors described in this topic are distinct from the SNMP error codes defined by the relevant RFCs.

All WinSNMP functions return the value SNMPAPI_FAILURE if the function fails. The WinSNMP application must immediately call the SnmpGetLastError function to retrieve extended error information when a WinSNMP function fails. For additional information about the extended error codes WinSNMP functions return, see the following topics:

  • WinSNMP Common Error Codes
  • Network Transport Errors

The WinSNMP errors that convey context-specific information are noted in each function's reference page.


WinSNMP Common Error Codes

The SnmpGetLastError function can return a general error code after a WinSNMP function fails. The following table lists the WinSNMP common error codes.

Error code | Meaning | Recommended action
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully either since program execution began, or since a call to the SnmpCleanup function completed successfully. | The application should call SnmpGetLastError before it calls any other WinSNMP API function when SnmpStartup fails. The SnmpGetLastError function returns extended error information about the failure of SnmpStartup.
SNMPAPI_ALLOC_ERROR | The application specified an invalid pointer, or an error occurred during memory allocation. The Microsoft WinSNMP implementation could not obtain sufficient resources to execute the request. | The application should provide valid memory pointers for all output parameters. It should free resources, reduce resource requirements, or facilitate a graceful shutdown. A graceful shutdown includes multiple calls to the SnmpClose function, one for each open WinSNMP session. It also includes a call to the SnmpCleanup function.
SNMPAPI_NOOP | The function did not complete successfully because all output parameters are NULL. | The application must specify at least one output parameter that is not NULL when calling a function that returns information to the application.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred. | The application should usually respond with a graceful shutdown. A graceful shutdown includes multiple calls to the SnmpClose function, one for each open WinSNMP session. It also includes a call to the SnmpCleanup function.

The WinSNMP errors that convey context-specific information are noted in each function's reference page.


Network Transport Errors

The Microsoft WinSNMP implementation can detect a network transport error after it transmits an SNMP message. When this occurs, the implementation sends a data receipt notification to the WinSNMP session that initiated the communication request. The implementation also returns SNMPAPI_FAILURE on the next call to the SnmpRecvMsg function for the session. The SnmpRecvMsg function fails with an extended error code that indicates a network transport layer error.

For a list of specific transport layer errors, see the reference pages for the SnmpRegister, SnmpSendMsg, and SnmpRecvMsg functions.


WinSNMP Function Return Values

The return value from a WinSNMP function call can be a handle to a resource that the Microsoft WinSNMP implementation allocates for the WinSNMP application.

The following table lists the five types of resource handles that the implementation allocates.

Handle type | Description
HSNMP_SESSION | Handle to a WinSNMP session
HSNMP_ENTITY | Handle to an SNMP entity
HSNMP_CONTEXT | Handle to an SNMP context
HSNMP_PDU | Handle to a protocol data unit
HSNMP_VBL | Handle to a variable binding list

For more information, see Resource Handle Objects.

The return value can also be an unsigned long integer value of the smiUINT32 type that represents an SNMPAPI_STATUS value.

The following table lists the WinSNMP status values and their meaning.

Status | Description
SNMPAPI_FAILURE | Indicates an error. Equates to 0 or NULL.
SNMPAPI_SUCCESS | Indicates the function completed successfully. Equates to 1 or a positive count.


WinSNMP Functions

The functions used with WinSNMP fall into the following functional groupings. An alphabetic list follows.

  • Communications Functions
  • Entity and Context Functions
  • Database Functions
  • PDU Functions
  • Utility Functions
  • Variable Binding Functions
  • WinSNMP Functions — Alphabetic List

WinSNMP Communications Functions

The WinSNMP communications functions provide an interface between the calling WinSNMP application and the Microsoft WinSNMP implementation. The implementation handles communication between the application and other management entities.

Function | Description
SnmpCancelMsg | Requests that the Microsoft WinSNMP implementation cancel retransmission attempts and time-out notifications for an SNMP request message.
SnmpCleanup | Informs the implementation that an application is disconnecting and no longer requires allocated resources. An application must call the SnmpCleanup function as the last WinSNMP function before it terminates.
SnmpClose | Enables the implementation to deallocate resources associated with a session, and to close communications mechanisms.
SnmpCreateSession | Requests the implementation to open a WinSNMP session and allocate resources and communications mechanisms. When developing new WinSNMP applications, it is recommended that you call the SnmpCreateSession function to open a WinSNMP session instead of calling the SnmpOpen function.
SnmpListen | Registers or unregisters a WinSNMP application as an SNMP agent.
SnmpOpen | Requests the implementation to open a WinSNMP session and allocate resources and communications mechanisms. When developing new WinSNMP applications, tt is recommended that you call the SnmpCreateSession function to open a WinSNMP session instead of calling the SnmpOpen function.
SnmpRecvMsg | Returns SNMP messages and outstanding trap data and notifications.
SnmpRegister | Informs the implementation that the application needs to register or unregister for traps and notifications.
SnmpSendMsg | Requests that the implementation transmit a protocol data unit.
SnmpStartup | Notifies the implementation to perform initialization procedures for the application. An application must call the SnmpStartup function successfully before it calls any other WinSNMP function.
SNMPAPI_CALLBACK | Notifies a WinSNMP session that an SNMP message or asynchronous event is available. Note: This callback function applies only to sessions opened as a result of a call to the SnmpCreateSession function.

WinSNMP Entity and Context Functions

The WinSNMP entity and context functions enable a WinSNMP application to specify user-friendly names for SNMP entities and contexts. The Microsoft WinSNMP implementation translates the name to its SNMPv1 or SNMPv2C components using the implementation's database.

Function | Description
SnmpContextToStr | Returns a string that identifies an SNMP context (a set of managed object resources).
SnmpEntityToStr | Returns a string that identifies an SNMP management entity.
SnmpFreeContext | Releases resources allocated by the SnmpStrToContext function for an SNMP context.
SnmpFreeEntity | Releases resources allocated by the SnmpStrToEntity function for an SNMP management entity.
SnmpSetPort | Changes the port assigned to an SNMP destination entity.
SnmpStrToContext | Returns a handle to SNMP context information that is specific to the implementation.
SnmpStrToEntity | Returns a handle to SNMP management entity information that is specific to the implementation.

WinSNMP Database Functions

The WinSNMP database functions provide a WinSNMP application with access to the current settings in the Microsoft WinSNMP implementation's store of administrative information. These functions permit changing the retransmission mode and the entity and context translation mode. The database functions also provide the application with the ability to manipulate the time-out and retry count values.

Function | Description
SnmpGetRetransmitMode | Returns the current setting of the retransmission mode.
SnmpGetRetry | Returns the retry count value, in units, for the retransmission of SNMP message requests.
SnmpGetTimeout | Returns the time-out value, in hundredths of a second, for the transmission of SNMP message requests.
SnmpGetTranslateMode | Returns the current setting of the entity and context translation mode.
SnmpGetVendorInfo | Retrieves information that identifies the WinSNMP vendor.
SnmpSetRetransmitMode | Changes the retransmission mode.
SnmpSetRetry | Changes the retry count value for the retransmission of SNMP message requests.
SnmpSetTimeout | Changes the time-out value for the transmission of SNMP message requests.
SnmpSetTranslateMode | Changes the entity and context translation mode.

WinSNMP PDU Functions

The WinSNMP PDU functions enable WinSNMP applications to extract and update the data elements (or fields) of a PDU. This includes PDUs returned by a call to the SnmpRecvMsg function or the SnmpDecodeMsg function. The PDU functions also construct PDUs for use in the SnmpSendMsg and SnmpEncodeMsg functions.

Function | Description
SnmpCreatePdu | Creates and initializes an SNMP protocol data unit.
SnmpDuplicatePdu | Duplicates an SNMP protocol data unit.
SnmpFreePdu | Releases resources associated with an SNMP protocol data unit created by the SnmpCreatePdu or the SnmpDuplicatePdu function.
SnmpGetPduData | Returns selected data elements from a specified SNMP protocol data unit.
SnmpSetPduData | Updates selected data elements in a specified SNMP protocol data unit.

WinSNMP Utility Functions

The WinSNMP utility functions enable a WinSNMP application to manage objects and SNMP messages across the WinSNMP interface.

Function | Description
SnmpDecodeMsg | Decodes an encoded or serialized SNMP message into its constituent components.
SnmpEncodeMsg | Creates an encoded SNMP message.
SnmpFreeDescriptor | Signals the Microsoft WinSNMP implementation that it should free the memory it allocated for a specific descriptor.
SnmpGetLastError | Returns the last-error code value for the last SNMP operation.
SnmpOidCompare | Compares two SNMP object identifiers.
SnmpOidCopy | Copies an SNMP object identifier.
SnmpOidToStr | Converts the internal binary representation of an SNMP object identifier to its dotted numeric string format.
SnmpStrToOid | Converts the dotted numeric string format of an SNMP object identifier to its internal binary representation.

WinSNMP Variable Binding Functions

The WinSNMP variable binding functions enable WinSNMP applications to construct and manipulate variable binding lists, and include them in PDUs.

Function | Description
SnmpCountVbl | Enumerates the variable binding entries in a specified variable binding list.
SnmpCreateVbl | Creates a new variable binding list.
SnmpDeleteVb | Removes a variable binding entry from a variable binding list.
SnmpDuplicateVbl | Copies a variable binding list.
SnmpFreeVbl | Releases resources for a variable binding list allocated previously by the SnmpCreateVbl or the SnmpDuplicateVbl function.
SnmpGetVb | Retrieves information from a specified variable binding entry.
SnmpSetVb | Changes variable binding entries in a variable binding list; appends new variable binding entries to an existing variable binding list.

WinSNMP Functions — Alphabetic List

SNMPAPI_CALLBACK
SnmpCancelMsg
SnmpCleanup
SnmpClose
SnmpContextToStr
SnmpCountVbl
SnmpCreatePdu
SnmpCreateSession
SnmpCreateVbl
SnmpDecodeMsg
SnmpDeleteVb
SnmpDuplicatePdu
SnmpDuplicateVbl
SnmpEncodeMsg
SnmpEntityToStr
SnmpFreeContext
SnmpFreeDescriptor
SnmpFreeEntity
SnmpFreePdu
SnmpFreeVbl
SnmpGetLastError
SnmpGetPduData
SnmpGetRetransmitMode
SnmpGetRetry
SnmpGetTimeout
SnmpGetTranslateMode
SnmpGetVb
SnmpGetVendorInfo
SnmpListen
SnmpOidCompare
SnmpOidCopy
SnmpOidToStr
SnmpOpen
SnmpRecvMsg
SnmpRegister
SnmpSendMsg
SnmpSetPduData
SnmpSetPort
SnmpSetRetransmitMode
SnmpSetRetry
SnmpSetTimeout
SnmpSetTranslateMode
SnmpSetVb
SnmpStartup
SnmpStrToContext
SnmpStrToEntity
SnmpStrToOid


SNMPAPI_CALLBACK

The Microsoft WinSNMP implementation calls the SNMPAPI_CALLBACK function to notify a WinSNMP session that an SNMP message or asynchronous event is available.

SNMPAPI_CALLBACK is a placeholder for an application- or library-defined callback function name.

SNMPAPI_STATUS CALLBACK SNMPAPI_CALLBACK(
  HSNMP_SESSION hSession,  // handle to the WinSNMP session
  HWND hWnd,               // handle to the notification window
  UINT wMsg,               // window notification message number
  WPARAM wParam,           // type of notification
  LPARAM lParam,           // request identifier of PDU
  LPVOID lpClientData      // optional application-defined data
);

Parameters

hSession
[in] Handle to the WinSNMP session.
hWnd
[in] Handle to a window of the WinSNMP application to notify when an asynchronous request completes, or when trap notification occurs. This parameter does not have significance for the WinSNMP session, but the implementation always passes the value to the callback function.
wMsg
[in] Specifies an unsigned integer that identifies the notification message to send to the WinSNMP application window. This parameter does not have significance for the WinSNMP session, but the implementation always passes the value to the callback function.
wParam
[in] Specifies an application-defined 32-bit value that identifies the type of notification. If this parameter is equal to zero, an SNMP message is available for the session. The application should call the SnmpRecvMsg function to retrieve the message. If this parameter is not equal to zero, it indicates an asynchronous event notification for the session. For additional information, see the following Remarks section.
lParam
[in] Specifies an application-defined 32-bit value that specifies the request identifier of the PDU being processed.
lpClientData
[in] If the lpClientData parameter was not NULL on the call to the SnmpCreateSession function for this session, this parameter is a pointer to application-defined data.

Return Values

The function must return SNMPAPI_SUCCESS to continue execution of the application. If the function returns any other value, the implementation responds as if the application called the SnmpClose function for the indicated session.

Remarks

When the implementation is executing the retransmission policy for the WinSNMP application and a transmission time-out occurs, the implementation informs the session of the error. In this situation the value of the wParam parameter would be SNMPAPI_TL_TIMEOUT. For a list of other transport layer errors, see the reference pages for the SnmpRegister, SnmpSendMsg, and SnmpRecvMsg functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCreateSession, SnmpClose


SnmpCancelMsg

A WinSNMP application calls the SnmpCancelMsg function to request that the Microsoft WinSNMP implementation cancel retransmission attempts and time-out notifications for an SNMP request message. The SnmpCancelMsg function is an element of the WinSNMP API, version 2.0.

SNMPAPI_STATUS SnmpCancelMsg(
  HSNMP_SESSION session, // handle to the WinSNMP session
  smiINT32 reqId         // request_id field of the PDU
);

Parameters

session
[in] Handle to the WinSNMP session that submitted the SNMP request message (PDU) to be canceled.
reqId
[in] Specifies a unique numeric value that identifies the PDU of interest. This parameter must match the request identifier (request_id) of the PDU parameter specified in the application's initial call to the SnmpSendMsg function.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_PDU_INVALID | The reqId parameter does not identify an outstanding message for the specified session.
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Calling the SnmpCancelMsg function is equivalent to calling the SnmpSetRetransmitMode function, for a specific SNMP message, with the retransmission mode equal to SNMPAPI_OFF.

For more information, see Canceling Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSendMsg, SnmpSetRetransmitMode


SnmpCleanup

The SnmpCleanup function informs the Microsoft WinSNMP implementation that the calling WinSNMP application no longer requires the implementation's services.

Note A WinSNMP application must call the SnmpCleanup function as the last WinSNMP function before it terminates.

SNMPAPI_STATUS SnmpCleanup(VOID);

Parameters

This function has no parameters.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS. Until the WinSNMP application successfully recalls the SnmpStartup function, any other call to a WinSNMP function returns SNMPAPI_FAILURE, with an extended error code of SNMPAPI_NOT_INITIALIZED.

If the function fails, the return value is SNMPAPI_FAILURE, but the WinSNMP application does not need to retry the call to SnmpCleanup. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Before the WinSNMP application calls SnmpCleanup, it should call the SnmpClose function once for each session the implementation opens as a result of a call to the SnmpCreateSession function.

When a WinSNMP application calls the SnmpCleanup function, the implementation deallocates all resources allocated to the application. However, it is recommended that a WinSNMP application free the specific resources that the implementation allocates for it with the WinSNMP function that corresponds to the resource. For additional information about freeing individual resources, see SnmpFreeEntity, SnmpFreeVbl, SnmpFreeDescriptor, SnmpFreeContext, and SnmpFreePdu.

If a WinSNMP application must perform an emergency exit, and it calls SnmpCleanup without freeing individual resources and without calling SnmpClose for every open session, the implementation deallocates all resources allocated to the WinSNMP application. However, to enable this functionality in the implementation, the application must still call SnmpCleanup.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCreateSession, SnmpStartup, SnmpClose, SnmpFreeEntity, SnmpFreeVbl, SnmpFreeDescriptor, SnmpFreeContext, SnmpFreePdu


SnmpClose

The SnmpClose function enables the Microsoft WinSNMP implementation to deallocate memory, resources, and data structures associated with a WinSNMP session. The WinSNMP SnmpClose function also closes communications mechanisms the implementation opened as a result of a call to the SnmpCreateSession function.

SNMPAPI_STATUS SnmpClose(
  HSNMP_SESSION session    // handle to the session to close
);

Parameters

session
[in] Handle to the WinSNMP session to close.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

It is recommended that a WinSNMP application call the SnmpClose function once for each session that the application opened using the SnmpCreateSession function. If a WinSNMP application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources. The implementation processes one SnmpCleanup call as if it were a series of SnmpClose calls, one call for each session opened as a result of a call to SnmpCreateSession.

When the implementation closes a session it discards all outstanding incoming and outgoing asynchronous requests and replies for the session. For additional information, see WinSNMP Sessions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCleanup, SnmpCreateSession


SnmpContextToStr

The WinSNMP SnmpContextToStr function returns a string that identifies an SNMP context, which is a set of managed object resources. The function returns the string in an smiOCTETS structure.

SNMPAPI_STATUS SnmpContextToStr(
  HSNMP_CONTEXT context,  // handle to the context
  smiLPOCTETS string      // pointer to a structure to receive the
                          // context string
);

Parameters

context
[in] Handle to the SNMP context of interest.
string
[out] Pointer to an smiOCTETS structure to receive the string that identifies the context of interest. The string can have a null-terminating byte.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpContextToStr returns. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP application must provide the address of a valid smiOCTETS structure for the string parameter. If the SnmpContextToStr function completes successfully, the Microsoft WinSNMP implementation initializes the len and ptr members of the structure. The WinSNMP application must call the SnmpFreeDescriptor function to enable the implementation to free the resources for these members.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and the entry exists in the implementation's database, the implementation returns the associated user-friendly name of the context. If an entry does not exist for the context name, SnmpContextToStr returns the SNMP community string.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the implementation also returns the SNMP community string.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOCTETS


SnmpCountVbl

A WinSNMP application calls the WinSNMP SnmpCountVbl function to enumerate the variable binding entries in the specified variable bindings list.

SNMPAPI_STATUS SnmpCountVbl(
  HSNMP_VBL vbl   // handle to the variable bindings list
);

Parameters

vbl
[in] Handle to the variable bindings list to enumerate.

Return Values

If the function succeeds, the return value is the count of variable binding entries in the variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_NOOP | The variable bindings list does not contain any variable binding entries at this time.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpCountVbl function returns an unsigned integer value that is the maximum value the WinSNMP application can specify for the index parameter in the SnmpGetVb, SnmpSetVb, and SnmpDeleteVb functions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpGetVb, SnmpSetVb, SnmpDeleteVb


SnmpCreatePdu

The WinSNMP SnmpCreatePdu function creates and initializes an SNMP protocol data unit (PDU).

HSNMP_PDU SnmpCreatePdu(
  HSNMP_SESSION session, // handle to the WinSNMP session
  smiINT PDU_type,       // PDU type
  smiINT32 request_id,   // PDU request identifier
  smiINT error_status,   // PDU error status, unless type is SNMP_PDU_GETBULK
  smiINT error_index,    // PDU error index, unless type is SNMP_PDU_GETBULK
  HSNMP_VBL varbindlist  // handle to the variable bindings list
);

Parameters

session
[in] Handle to the WinSNMP session.
PDU_type
[in] Specifies a PDU type that identifies the SNMP operation. This parameter can be NULL, or it can be one of the following values. If this parameter is NULL, the Microsoft WinSNMP implementation supplies the default PDU type SNMP_PDU_GETNEXT. The only type of trap PDU you can create with a call to the SnmpCreatePdu function is an SNMPv2C trap PDU.
Value | Meaning
SNMP_PDU_GET | Search and retrieve a value from a specified SNMP variable.
SNMP_PDU_GETNEXT | Search and retrieve the value of an SNMP variable without knowing the exact name of the variable.
SNMP_PDU_RESPONSE | Reply to an SNMP_PDU_GET or an SNMP_PDU_GETNEXT request.
SNMP_PDU_SET | Store a value in a specified SNMP variable.
SNMP_PDU_GETBULK | Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP | Alerts the management system to an event under SNMPv2C.

request_id
[in] Specifies a unique numeric value that the WinSNMP application supplies to identify the PDU. If this parameter is NULL, the implementation assigns a value.
error_status
[in] If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the non_repeaters field of the PDU. For other PDU types, this parameter specifies a value for the error_status field of the PDU. This parameter can be NULL.
error_index
[in] If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter specifies a value for the max_repetitions field of the PDU. For other PDU types, this parameter specifies a value for the error_index field of the PDU. This parameter can be NULL.
varbindlist
[in] Handle to a structure that represents an SNMP variable bindings list. This parameter can be NULL.

Return Values

If the function succeeds, the return value is the handle to a new SNMP PDU.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_VBL_INVALID | The variable bindings list is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP application must create a PDU before it calls the SnmpSendMsg or the SnmpEncodeMsg functions.

All of the parameters of the SnmpCreatePdu function are required. However, all parameters, except the session parameter, can be NULL. In this instance, the new PDU has the following default values.

Field | Contents
PDU_type | SNMP_PDU_GETNEXT
request_id | The implementation generates a numeric value.
error_status | SNMP_ERROR_NOERROR
error_index | 0
varbindlist | NULL

The application must call the SnmpFreePdu function to release the resources that the SnmpCreatePdu function allocates for the new PDU.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreePdu, SnmpSendMsg, SnmpEncodeMsg


SnmpCreateSession

The SnmpCreateSession function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP application. The application can specify how the implementation should inform the WinSNMP session of available SNMP messages and asynchronous events. The application can specify a window notification message or an SNMPAPI_CALLBACK function to notify the session.

The SnmpCreateSession function is an element of the WinSNMP API, version 2.0. When developing new WinSNMP applications, it is recommended that you call SnmpCreateSession to open a WinSNMP session instead of calling the SnmpOpen function.

HSNMP_SESSION SnmpCreateSession(
  HWND hWnd,                    // handle to the notification window
  UINT wMsg,                    // window notification message number
  SNMPAPI_CALLBACK fCallback,   // notification callback function
  LPVOID lpClientData           // pointer to callback function data
);

Parameters

hWnd
[in] Handle to a window of the WinSNMP application to notify when an asynchronous request completes, or when trap notification occurs. This parameter is required for window notification messages for the session.
wMsg
[in] Specifies an unsigned integer that identifies the notification message to send to the WinSNMP application window. This parameter is required for window notification messages for the session.
fCallback
[in] Specifies the address of an application-defined, session-specific SNMPAPI_CALLBACK function. The implementation will call this function to inform the WinSNMP session when notifications are available.

This parameter is required to specify callback notifications for the session. This parameter must be NULL to specify window notification messages for the session. For additional information, see the following Remarks section.

lpClientData
[in] Pointer to application-defined data to pass to the callback function specified by the fCallback parameter. This parameter is optional and can be NULL. If the fCallback parameter is NULL, the implementation ignores this parameter.

Return Values

If the function succeeds, the return value is a handle that identifies the WinSNMP session that the implementation opens for the calling application.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_HWND_INVALID | The fCallback parameter is NULL, but the hWnd parameter is not a valid window handle.
SNMPAPI_MSG_INVALID | The fCallback parameter is NULL, but the wMsg parameter is not a valid message value.
SNMPAPI_MODE_INVALID | The fCallback parameter is NULL and the hWnd and wMsg parameters are valid individually. However, the values are mutually incompatible on the Windows platform.
SNMPAPI_OPERATION_INVALID | The combination of parameter values does not specify callback notifications or window notification messages.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpCreateSession function returns a unique handle to each open WinSNMP session within the calling WinSNMP application. The application must use the session handle that SnmpCreateSession returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation.

It is recommended that a WinSNMP application call the SnmpClose function once for each session that the implementation opens as a result of a call to the SnmpCreateSession function. If a WinSNMP application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources.

Callback Notifications

If the fCallback parameter is not NULL on a successful call to the SnmpCreateSession function, the implementation alerts the session to notifications using the callback function specified by the fCallback parameter.

Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using callback notifications.

hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Window Notification Messages

The SnmpCreateSession function passes to the implementation the handle to an application window and a notification message identifier. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpCreateSession.

One WinSNMP application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP application specify a unique wMsg parameter for each session.

Following is an example of a call to the SnmpCreateSession function, requesting that the implementation signal the session about messages and events using window notification messages.

hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SNMPAPI_CALLBACK, SnmpClose, SnmpCleanup, SnmpRecvMsg


SnmpCreateVbl

The WinSNMP SnmpCreateVbl function creates a new variable bindings list for the calling WinSNMP application. If the name and value parameters are not NULL, SnmpCreateVbl uses their values to create the first variable binding entry for the new variable bindings list. The SnmpCreateVbl function returns a handle to the new variable bindings list and allocates any necessary memory for it.

HSNMP_VBL SnmpCreateVbl(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  smiLPCOID name,         // pointer to the variable name
  smiLPCVALUE value       // pointer to the value to associate
                          //   with the variable
);

Parameters

session
[in] Handle to the WinSNMP session.
name
[in] Pointer to an smiOID structure that contains the variable name for the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.
value
[in] Pointer to an smiVALUE structure that contains a value to associate with the variable in the first variable binding entry. This parameter can be NULL. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is a handle to a new variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_OID_INVALID | The name parameter references an invalid smiOID structure.
SNMPAPI_SYNTAX_INVALID | The syntax member of the structure pointed to by the value parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpCreateVbl function uses the values of the name and value parameters to create and initialize the first variable binding entry of a new variable bindings list. If the name parameter is NULL, the Microsoft WinSNMP implementation ignores the value parameter and creates an empty variable bindings list.

If the name parameter is not NULL, but the value parameter is NULL, the implementation creates and initializes the first variable binding entry in the variable bindings list. It initializes the syntax member of the structure pointed to by the value parameter with the value SNMP_SYNTAX_NULL.

The WinSNMP application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl. For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpFreeVbl, smiOID, smiVALUE


SnmpDecodeMsg

The WinSNMP SnmpDecodeMsg function decodes an encoded SNMP message into its components. This function performs the opposite action of the WinSNMP SnmpEncodeMsg function.

SNMPAPI_STATUS SnmpDecodeMsg(
  HSNMP_SESSION session,     // handle to the WinSNMP session
  LPHSNMP_ENTITY srcEntity,  // handle to the source entity
  LPHSNMP_ENTITY dstEntity,  // handle to the target entity
  LPHSNMP_CONTEXT context,   // handle to the context
  LPHSNMP_PDU pdu,           // handle to the PDU
  smiLPCOCTETS msgBufDesc    // pointer to the message buffer
);

Parameters

session
[in] Handle to the WinSNMP session. This parameter is required. For additional information, see the following Remarks section.
srcEntity
[out] Pointer to a variable that receives a handle to the source management entity. For more information, see the following Remarks section.
dstEntity
[out] Pointer to a variable that receives a handle to the target management entity. For more information, see the following Remarks section.
context
[out] Pointer to a variable that receives a handle to the context (a set of managed object resources) that the target management entity controls.
pdu
[out] Pointer to a variable that receives a handle to the SNMP protocol data unit (PDU).
msgBufDesc
[in] Pointer to an smiOCTETS structure that contains the SNMP message to decode into its components. The len member of the structure specifies the maximum number of bytes to process; the ptr member points to the encoded SNMP message.

Return Values

If the function succeeds, the return value is the number of decoded bytes. This value can be equal to, or less than, the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The pdu parameter is invalid.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient. No output parameters were created.
SNMPAPI_MESSAGE_INVALID | The SNMP message format in the buffer indicated by the msgBufDesc parameter is invalid. No output parameters were created.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The Microsoft WinSNMP implementation returns a value of zero in the srcEntity and the dstEntity parameters when an application submits an SNMPv1 or an SNMPv2C message to the SnmpDecodeMsg function. This is because the message format does not include the address information necessary to create WinSNMP entity resources.

The Microsoft WinSNMP implementation allocates resources to the WinSNMP application as a result of a successful call to the SnmpDecodeMsg function. It is recommended that the WinSNMP application free individual resources with the WinSNMP function that corresponds to the resource. For additional information, see Freeing WinSNMP Descriptors and WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpEncodeMsg, SnmpFreeEntity, SnmpFreeContext, SnmpFreePdu, SnmpSendMsg, smiOCTETS


SnmpDeleteVb

The WinSNMP SnmpDeleteVb function removes a variable binding entry from a variable bindings list.

SNMPAPI_STATUS SnmpDeleteVb(
  HSNMP_VBL vbl,   // handle to the variable bindings list
  smiUINT32 index  // position of the variable binding entry
                   //   in the list
);

Parameters

vbl
[in] Handle to the variable bindings list to update.
index
[in] Specifies an unsigned long integer variable that identifies the variable binding entry to remove. This variable contains the position of the variable binding entry, within the variable bindings list.

Valid values for this parameter are in the range from 1 to n, where 1 indicates the first variable binding entry in the variable bindings list, and n is the total number of entries in the variable bindings list. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP application can use the SnmpDeleteVb function to delete invalid variable binding entries. When an SNMP_PDU_RESPONSE protocol data unit (PDU) includes an error that indicates an invalid variable binding entry, the application can call SnmpDeleteVb to delete the entry. Then the application can resubmit the request PDU with a call to the SnmpSendMsg function, without the invalid variable binding entry in the variable bindings list. Request PDUs include the SNMP_PDU_GET, SNMP_PDU_GETNEXT, and SNMP_PDU_GETBULK PDU data types.

After the SnmpDeleteVb function deletes a variable binding entry, the index value of all entries after the deleted entry will decrement by one. A call to the SnmpCountVbl function returns the new total number of entries in the variable bindings list. The new total is one less than the count returned by a call to SnmpCountVbl before the current call to SnmpDeleteVb.

If a WinSNMP application calls the SnmpDeleteVb function and deletes the last variable binding entry in a variable bindings list, the result is an empty variable bindings list. The variable bindings list still has a valid handle and the WinSNMP application must release the handle with a call to the SnmpFreeVbl function.

The following are valid values to use for the index parameter:

  • The return value from a call to the SnmpCountVbl function
  • The error index field of an SNMP_PDU_RESPONSE PDU returned by a call to the SnmpRecvMsg function

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCountVbl, SnmpRecvMsg, SnmpFreeVbl


SnmpDuplicatePdu

The WinSNMP SnmpDuplicatePdu function duplicates the SNMP protocol data unit (PDU) that the PDU parameter identifies, allocating any necessary memory for the duplicate PDU.

HSNMP_PDU SnmpDuplicatePdu(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  HSNMP_PDU PDU               // handle to the PDU to duplicate
);

Parameters

session
[in] Handle to the WinSNMP session.
PDU
[in] Handle to the PDU to duplicate. The SnmpDuplicatePdu function provides a unique handle to each PDU within the calling application.

Return Values

If the function succeeds, the return value is a handle that identifies the new duplicate PDU.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_PDU_INVALID | The PDU handle is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

To release resources allocated by the SnmpDuplicatePdu function for a new PDU, a WinSNMP application must call the SnmpFreePdu function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreePdu, SnmpGetPduData


SnmpDuplicateVbl

The WinSNMP SnmpDuplicateVbl function copies a variable bindings list for the specified WinSNMP session. This function returns a handle to the copied variable bindings list and allocates any necessary memory for it.

HSNMP_VBL SnmpDuplicateVbl(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  HSNMP_VBL vbl           // handle to the variable bindings
                          //   list to duplicate
);

Parameters

session
[in] Handle to the WinSNMP session.
vbl
[in] Handle to the variable bindings list to copy. The source variable bindings list can be empty.

Return Values

If the function succeeds, the return value is a handle to a new variable bindings list.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session handle is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpDuplicateVbl function creates a new variable bindings list for the specified WinSNMP session. This function initializes the new list with a copy of the data in the source variable bindings list.

The handle the SnmpDuplicateVbl function returns is unique among the variable bindings list handles that are active within the WinSNMP application.

The WinSNMP application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl. For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeVbl, SnmpCreateVbl


SnmpEncodeMsg

The Microsoft WinSNMP implementation uses the parameters passed in the WinSNMP SnmpEncodeMsg function to encode an SNMP message. The implementation returns the encoded SNMP message to the WinSNMP application in the buffer specified by the msgBufDesc parameter.

SNMPAPI_STATUS SnmpEncodeMsg(
  HSNMP_SESSION session,     // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,    // handle to the source entity
  HSNMP_ENTITY dstEntity,    // handle to the target entity
  HSNMP_CONTEXT context,     // handle to the context
  HSNMP_PDU pdu,             // handle to the PDU
  smiLPOCTETS msgBufDesc     // pointer to the message buffer
);

Parameters

session
[in] Handle to the WinSNMP session.
srcEntity
[in] Handle to the management entity that initiates the request to encode the SNMP message.
dstEntity
[in] Handle to the target management entity.
context
[in] Handle to the context (a set of managed object resources) that the target management entity controls.
pdu
[in] Handle to the PDU that contains the SNMP operation request.
msgBufDesc
[out] Pointer to an smiOCTETS structure that receives the encoded SNMP message.

Return Values

If the function succeeds, the return value is the length, in bytes, of the encoded SNMP message. This number is also the value of the len member of the smiOCTETS structure pointed to by the msgBufDesc parameter.

If the function fails, the return value is SNMPAPI_FAILURE. For additional information, see the following Remarks section. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The pdu parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The first five parameters passed to the SnmpEncodeMsg function are the same parameters that are passed to the SnmpSendMsg function.

The WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOCTETS structure. This is the structure pointed to by the msgBufDesc parameter. For additional information, see WinSNMP Data Management Concepts.

On input, the SnmpEncodeMsg function ignores the members of the structure pointed to by the msgBufDesc parameter. The implementation overwrites the members of the structure if the function completes successfully.

The implementation verifies the format of the first five input parameters. If one of the parameters is invalid, SnmpEncodeMsg returns SNMPAPI_FAILURE, and SnmpGetLastError returns an extended error code.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeDescriptor, SnmpDecodeMsg, SnmpSendMsg, smiOCTETS


SnmpEntityToStr

The WinSNMP SnmpEntityToStr function returns a string that identifies an SNMP management entity.

SNMPAPI_STATUS SnmpEntityToStr(
  HSNMP_ENTITY entity, // handle to the entity
  smiUINT32 size,      // buffer size, in bytes, for output string
  LPSTR string         // pointer to the buffer to receive the
                       //   output string
);

Parameters

entity
[in] Handle to the SNMP management entity of interest.
size
[in] Specifies the size, in bytes, of the buffer pointed to by the string parameter. The WinSNMP application must allocate a buffer that is large enough to contain the output string.
string
[out] Pointer to a buffer to receive the null-terminated string that identifies the SNMP management entity of interest.

Return Values

If the function succeeds, the return value is the number of bytes, including a terminating null byte, that SnmpEntityToStr returns in the string buffer. This value can be less than or equal to the value of the size parameter, but it cannot be greater.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The entity parameter is invalid.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the type of output string SnmpEntityToStr returns. For additional information, see Support for IPX Address Strings in WinSNMP and Setting the Entity and Context Translation Mode.

When the entity and context translation mode is SNMPAPI_TRANSLATED, and an entry exists in the implementation's database, the implementation returns the associated user-friendly name of the management entity. If an entry does not exist for the management entity, SnmpEntityToStr returns the literal SNMP transport address of the management entity.

When the entity and context translation mode is SNMPAPI_UNTRANSLATED_V1 or SNMPAPI_UNTRANSLATED_V2, the Microsoft WinSNMP implementation also returns the literal SNMP transport address of the management entity.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToEntity


SnmpFreeContext

The WinSNMP SnmpFreeContext function releases resources associated with an SNMP context, which is a set of managed object resources.

SNMPAPI_STATUS SnmpFreeContext(
  HSNMP_CONTEXT context    // handle to the context to release
);

Parameters

context
[in] Handle to the SNMP context that will have its resources released.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

When the WinSNMP application calls the SnmpClose function or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocated for the WinSNMP session. However, it is recommended that the WinSNMP application free individual resources with the WinSNMP function that corresponds to the resource. For example, applications should call the SnmpFreeContext function to release resources allocated by a call to the SnmpStrToContext function. This reduces the implementation's work load, and should enhance the service of the implementation to all applications.

For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpStrToContext


SnmpFreeDescriptor

A WinSNMP application uses the SnmpFreeDescriptor function to inform the Microsoft WinSNMP implementation that it no longer requires access to a descriptor object. This WinSNMP function signals the implementation to free the memory it allocated for the descriptor object.

SNMPAPI_STATUS SnmpFreeDescriptor(
  smiUINT32 syntax,       // data type of target descriptor object
  smiLPOPAQUE descriptor  // pointer to the target descriptor object
);

Parameters

syntax
[in] Specifies the syntax data type of the target descriptor object.
descriptor
[in] Pointer to an smiOPAQUE structure that contains the target descriptor object to release.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SYNTAX_INVALID | The syntax parameter is invalid.
SNMPAPI_OPERATION_INVALID | The descriptor parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The implementation allocates and deallocates memory for output descriptor objects with variable lengths. This memory allocation and deallocation are restricted to the implementation, except for the interface that the SnmpFreeDescriptor function provides. For additional information, see Freeing WinSNMP Descriptors.

The implementation returns the SNMPAPI_OPERATION_INVALID error code if the descriptor parameter specifies a memory allocation that the implementation released in a prior call to SnmpFreeDescriptor. The function returns the same error code if the descriptor parameter specifies a memory allocation that the implementation did not make for the calling WinSNMP application.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToOid, SnmpOidCopy, SnmpEncodeMsg


SnmpFreeEntity

The WinSNMP SnmpFreeEntity function releases resources associated with an SNMP management entity.

SNMPAPI_STATUS SnmpFreeEntity(
  HSNMP_ENTITY entity   // handle to the entity to release
);

Parameters

entity
[in] Handle to the SNMP management entity that will have its resources released.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The entity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

When the WinSNMP application calls the SnmpClose function or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocated for the WinSNMP session. However, it is recommended that the WinSNMP application free individual resources by using the WinSNMP function that corresponds to the resource. For example, applications should call the SnmpFreeEntity function to release resources allocated by a call to the SnmpStrToEntity function. This reduces the implementation's work load, and should enhance the implementation's service to all applications.

For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpStrToEntity


SnmpFreePdu

The WinSNMP SnmpFreePdu function releases resources associated with an SNMP protocol data unit (PDU) created by the SnmpCreatePdu or the SnmpDuplicatePdu function.

SNMPAPI_STATUS SnmpFreePdu(
  HSNMP_PDU PDU     // handle to the PDU to free
);

Parameters

PDU
[in] Handle to the SNMP PDU to free.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_PDU_INVALID | The PDU handle is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

If the application calls the SnmpClose or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocates for the WinSNMP session. However, it is recommended that the application free individual resources with the WinSNMP function that corresponds to the resource. This reduces the implementation's work load, and should enhance the implementation's service to all applications. The application should use the SnmpFreeVbl function to deallocate variable bindings list resources. For additional information, see WinSNMP Data Management Concepts.

Under WinSNMP, a variable binding entry exists only within a variable bindings list, even if the variable bindings list contains just one entry.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeVbl, SnmpClose, SnmpCleanup


SnmpFreeVbl

The WinSNMP SnmpFreeVbl function releases resources associated with a variable bindings list. These are resources allocated previously by a call to the SnmpCreateVbl function or the SnmpDuplicateVbl function in a WinSNMP application.

SNMPAPI_STATUS SnmpFreeVbl(
  HSNMP_VBL vbl       // handle to the variable bindings list
);

Parameters

vbl
[in] Handle to the variable bindings list to release.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The WinSNMP application must release the resources associated with each variable bindings list. It should do this by matching each call to the SnmpCreateVbl and SnmpDuplicateVbl functions with a corresponding call to the SnmpFreeVbl function. To avoid memory leaks, a WinSNMP application must call SnmpFreeVbl before it reuses the handle to a variable bindings list in a subsequent call to SnmpCreateVbl or SnmpDuplicateVbl.

If the application calls the SnmpClose or the SnmpCleanup function, the Microsoft WinSNMP implementation frees all resources it allocates for the WinSNMP session. However, even if the application does not reuse a variable bindings list handle, it is recommended that the application free individual variable bindings resources with the SnmpFreeVbl function. This reduces the implementation's work load, and should enhance its service to all applications. For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpCreateVbl, SnmpClose, SnmpCleanup


SnmpGetLastError

The WinSNMP SnmpGetLastError function returns the calling application's last-error code value. The value indicates the reason why the last function call executed by the WinSNMP application failed.

SNMPAPI_STATUS SnmpGetLastError(
  HSNMP_SESSION session     // handle to the WinSNMP session
);

Parameters

session
[in] Handle to the WinSNMP session. This parameter can also be NULL.

In certain cases, when a function call fails you can pass a NULL session value to the SnmpGetLastError function to retrieve the last-error code value. This is true for function calls that do not involve a session parameter, and cases in which the session parameter value is invalid. These cases are noted in the Return Values section on the function's reference page.

A single-thread application can pass a NULL session value to SnmpGetLastError to retrieve last-error information for the entire application.

For more information, see the following Remarks and Return Values sections.

Return Values

If the session parameter is a valid WinSNMP session handle, the SnmpGetLastError function returns the last WinSNMP error that occurred for the indicated session.

If the session parameter is NULL — for example, if the SnmpStartup function fails, SnmpGetLastError returns the last WinSNMP error that occurred.

Remarks

A WinSNMP application must call SnmpGetLastError immediately after a function fails, to retrieve the last-error code. If another function fails, it overwrites the last-error code set by the most recently failed function. For more information, see WinSNMP Error Codes.

Although the session parameter accommodates both multithread and single-thread Windows operating environments, the potential still exists for the last-error code from one thread to overwrite the last-error code from another thread.

Note that SnmpGetLastError must be able to return the last-error code to a WinSNMP application under the following conditions:

  • After the SnmpStartup function fails
  • Before the SnmpCreateSession function creates any WinSNMP sessions for the instance of the application
  • After the SnmpClose function closes all WinSNMP sessions for the instance of the application
  • After the SnmpCleanup function disconnects the WinSNMP application from the Microsoft WinSNMP implementation

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStartup, SnmpCreateSession, SnmpClose, SnmpCleanup


SnmpGetPduData

The WinSNMP SnmpGetPduData function returns selected data fields from a specified SNMP protocol data unit (PDU).

SNMPAPI_STATUS SnmpGetPduData(
  HSNMP_PDU PDU,            // handle to the PDU
  smiLPINT PDU_type,        // PDU_type field of the PDU
  smiLPINT32 request_id,    // request_id field of the PDU
  smiLPINT error_status,    // error_status field of the PDU
  smiLPINT error_index,     // error_index field of the PDU
  LPHSNMP_VBL varbindlist   // handle to the variable bindings list
);

Parameters

PDU
[in] Handle to the SNMP PDU.
PDU_type
[out] Pointer to a variable that receives the PDU_type field of the specified PDU. This parameter can be NULL, or one of the following values.
Value | Meaning
SNMP_PDU_GET | Search and retrieve a value from a specified SNMP variable.
SNMP_PDU_GETNEXT | Search and retrieve the value of an SNMP variable without knowing the exact name of the variable.
SNMP_PDU_RESPONSE | Reply to an SNMP_PDU_GET or an SNMP_PDU_GETNEXT request.
SNMP_PDU_SET | Store a value in a specified SNMP variable.
SNMP_PDU_GETBULK | Search and retrieve multiple values with a single request.
SNMP_PDU_TRAP | Alerts the management system to an extraordinary event under SNMPv2C.

request_id
[out] Pointer to a variable that receives the request_id field of the specified PDU. This parameter can be NULL.
error_status
[out] Pointer to a variable that receives the error_status field of the specified PDU. If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the non_repeaters field of the PDU.

This parameter can be NULL, or one of the following values. The first six errors are common to the SNMP version 1 (SNMPv1) and SNMP version 2C frameworks (SNMPv2C). The remaining errors are available under SNMPv2C only.
Error code | Meaning
SNMP_ERROR_NOERROR | The agent reports that no errors occurred during transmission.
SNMP_ERROR_TOOBIG | The agent could not place the results of the requested SNMP operation into a single SNMP message.
SNMP_ERROR_NOSUCHNAME | The requested SNMP operation identified an unknown variable.
SNMP_ERROR_BADVALUE | The requested SNMP operation tried to change a variable but it specified either a syntax or value error.
SNMP_ERROR_READONLY | The requested SNMP operation tried to change a variable that was not allowed to change, according to the community profile of the variable.
SNMP_ERROR_GENERR | An error other than one of those listed here occurred during the requested SNMP operation.
SNMP_ERROR_NOACCESS | The specified SNMP variable is not accessible.
SNMP_ERROR_WRONGTYPE | The value specifies a type that is inconsistent with the type required for the variable.
SNMP_ERROR_WRONGLENGTH | The value specifies a length that is inconsistent with the length required for the variable.
SNMP_ERROR_WRONGENCODING | The value contains an Abstract Syntax Notation One (ASN.1) encoding that is inconsistent with the ASN.1 tag of the field.
SNMP_ERROR_WRONGVALUE | The value cannot be assigned to the variable.
SNMP_ERROR_NOCREATION | The variable does not exist, and the agent cannot create it.
SNMP_ERROR_INCONSISTENTVALUE | The value is inconsistent with values of other managed objects.
SNMP_ERROR_RESOURCEUNAVAILABLE | Assigning the value to the variable requires allocation of resources that are currently unavailable.
SNMP_ERROR_COMMITFAILED | No validation errors occurred, but no variables were updated.
SNMP_ERROR_UNDOFAILED | No validation errors occurred. Some variables were updated because it was not possible to undo their assignment.
SNMP_ERROR_AUTHORIZATIONERROR | An authorization error occurred.
SNMP_ERROR_NOTWRITABLE | The variable exists but the agent cannot modify it.
SNMP_ERROR_INCONSISTENTNAME | The variable does not exist; the agent cannot create it because the named object instance is inconsistent with the values of other managed objects.

error_index
[out] Pointer to a variable that receives the error_index field of the specified PDU.

If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter receives the value of the max_repetitions field of the specified PDU. This parameter can be NULL.

varbindlist
[out] Pointer to a variable that receives a handle to the variable bindings list field of the specified PDU. This parameter can be NULL. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_NOOP | All output parameters are NULL. The SNMP operation was not performed.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

All parameters of the SnmpGetPduData function are required. However, all parameters, except the PDU parameter, can be NULL. In parameters the application passes as NULL, the SnmpGetPduData function does not return a value.

The SnmpGetPduData function always returns a handle to a new variable bindings list object if the varbindlist parameter is not NULL. Additionally, if the PDU parameter specifies a new PDU, the function also attaches a handle to the new PDU.

When an application calls SnmpGetPduData with a varbindlist parameter that is not NULL, but the PDU parameter specifies an existing PDU, the function returns a handle to a new duplicate variable bindings list. The function call does not disturb the handle attached to the existing PDU. An existing PDU is one that an application creates with a call to the SnmpCreatePdu function, or one that the application receives and then reads using a call to SnmpGetPduData.

When an application creates a PDU with SnmpCreatePdu, or after the application reads a PDU using SnmpGetPduData, the Microsoft WinSNMP implementation expects that the application "knows" the values of the PDU fields. If an application reads a PDU a second time with SnmpGetPduData, the call results in a copy of the variable bindings list of the specified PDU. This type of call to SnmpGetPduData also duplicates the handle to the PDU.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpDuplicateVbl, SnmpCreatePdu


SnmpGetRetransmitMode

The WinSNMP SnmpGetRetransmitMode function returns the current setting of the retransmission mode to a WinSNMP application. The Microsoft WinSNMP implementation uses the retransmission mode to govern transmission time-outs and retransmission attempts on calls to the SnmpSendMsg function.

SNMPAPI_STATUS SnmpGetRetransmitMode(
  smiLPUINT32 nRetransmitMode  // current retransmission mode
);

Parameters

nRetransmitMode
[out] Pointer to an unsigned long integer variable to receive the current retransmission mode in effect for the implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_ON | The implementation is executing the WinSNMP application's retransmission policy.
SNMPAPI_OFF | The implementation is not executing the WinSNMP application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. If SnmpGetRetransmitMode fails, the value of the nRetransmitMode parameter has no meaning for the application. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP application, rather than an agent application, calls the SnmpGetRetransmitMode function. For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStartup, SnmpSetRetransmitMode


SnmpGetRetry

The WinSNMP SnmpGetRetry function returns the retry count value, in units, for the retransmission of SNMP message requests. The retry count applies to calls that a WinSNMP application makes to the SnmpSendMsg function for a specified management entity.

SNMPAPI_STATUS SnmpGetRetry(
  HSNMP_ENTITY hEntity,      // destination management entity
  smiLPUINT32 nPolicyRetry,  // retry count value from the database
  smiLPUINT32 nActualRetry   // last actual or estimated response
                             // retry count
);

Parameters

hEntity
[in] Handle to the destination management entity of interest.
nPolicyRetry
[out] Pointer to an unsigned long integer variable to receive the retry count value for the specified management entity. This is a value that the Microsoft WinSNMP implementation stores in a database. If you do not need the information returned in this parameter, nPolicyRetry must be a NULL pointer.
nActualRetry
[out] Pointer to an unsigned long integer variable to receive the last actual or estimated retry count for the destination entity, as reported by the implementation. If you do not need the information returned in this parameter, nActualRetry must be a NULL pointer. If this parameter is a valid pointer, the function returns 0. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_NOOP | The nPolicyRetry and nActualRetry parameters are both NULL. The operation was not performed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP application, rather than an agent application, calls the SnmpGetRetry function.

A WinSNMP application can modify the retry count value with a call to the SnmpSetRetry function.

The WinSNMP application can monitor the value of the nActualRetry parameter and compare it to the value of the nPolicyRetry parameter to optimize transmission performance. For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSetRetry, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpGetTimeout

The WinSNMP SnmpGetTimeout function returns the time-out value, in hundredths of a second, for the transmission of SNMP message requests. The time-out value applies to calls that a WinSNMP application makes to the SnmpSendMsg function for a specified management entity.

SNMPAPI_STATUS SnmpGetTimeout(
  HSNMP_ENTITY hEntity,          // destination management entity
  smiLPTIMETICKS nPolicyTimeout, // time-out value from the database
  smiLPTIMETICKS nActualTimeout  // last actual or estimated response time
);

Parameters

hEntity
[in] Handle to the destination management entity of interest.
nPolicyTimeout
[out] Pointer to an integer variable to receive the time-out value, in hundredths of a second, for the specified management entity. This is a value that the Microsoft WinSNMP implementation stores in a database. If you do not need the information returned in this parameter, nPolicyTimeout must be a NULL pointer.
nActualTimeout
[out] Pointer to an integer variable to receive the last actual or estimated response interval for the destination entity, as reported by the implementation. If you do not need the information returned in this parameter, nActualTimeout must be a NULL pointer. If this parameter is a valid pointer, the function returns 0. For additional information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_NOOP | The nPolicyTimeout and nActualTimeout parameters are both NULL. The operation was not performed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP application, rather than an agent application, calls the SnmpGetTimeout function.

The time-out period is the interval between the application's call to the SnmpSendMsg function and its call to the SnmpRecvMsg function.

A WinSNMP application can modify the time-out value with a call to the SnmpSetTimeout function.

The WinSNMP application can monitor the value of the nActualTimeout parameter and compare it to the value of the nPolicyTimeout parameter to optimize transmission performance. For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSetTimeout, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpGetTranslateMode

The WinSNMP SnmpGetTranslateMode function returns the current setting of the entity and context translation mode to a WinSNMP application. The entity and context translation mode affects the interpretation and return of WinSNMP input and output string parameters.

SNMPAPI_STATUS SnmpGetTranslateMode(
  smiLPUINT32 nTranslateMode  // current entity/context translation mode
);

Parameters

nTranslateMode
[out] Pointer to an unsigned long integer variable to receive the entity and context translation mode in effect for the Microsoft WinSNMP implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of zero in the version field.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of 1 in the version field.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. If SnmpGetTranslateMode fails, the value of the nTranslateMode parameter has no meaning for the application. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The entity and context translation mode affects calls to the SnmpStrToEntity, SnmpStrToContext, SnmpContextToStr and SnmpEntityToStr functions. For additional information, see Setting the Entity and Context Translation Mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToContext, SnmpStrToEntity, SnmpContextToStr, SnmpEntityToStr, SnmpStartup, SnmpSetTranslateMode


SnmpGetVb

A WinSNMP application calls the SnmpGetVb function to retrieve information from a variable bindings list. This WinSNMP function retrieves a variable name and its associated value from the variable binding entry specified by the index parameter.

SNMPAPI_STATUS SnmpGetVb(
  HSNMP_VBL vbl,    // handle to the variable bindings list
  smiUINT32 index,  // position of the variable binding entry
                    //   in the list
  smiLPOID name,    // pointer to the structure to receive the
                    //   variable name
  smiLPVALUE value  // pointer to the structure to receive the
                    //   associated value
);

Parameters

vbl
[in] Handle to the variable bindings list to retrieve.
index
[in] Specifies an unsigned long integer variable that identifies the variable binding entry to retrieve. This variable contains the position of the variable binding entry, within the variable bindings list.

Valid values for this parameter are in the range from 1 to n, where 1 indicates the first variable binding entry in the variable bindings list, and n is the total number of entries in the list. For additional information, see the following Remarks section.

name
[out] Pointer to an smiOID structure to receive the variable name of the variable binding entry.
value
[out] Pointer to an smiVALUE structure to receive the value associated with the variable identified by the name parameter.

If the function succeeds, the syntax member of the structure pointed to by the value parameter can be one of the following syntax data types. For additional information, see RFC 1902, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)."
Syntax data type | Meaning
SNMP_SYNTAX_INT | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_OCTETS | Indicates an octet string variable that is binary or textual data.
SNMP_SYNTAX_NULL | Indicates a NULL value.
SNMP_SYNTAX_OID | Indicates an object identifier variable that is an assigned name with a maximum of 128 subidentifiers.
SNMP_SYNTAX_INT32 | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_IPADDR | Indicates a 32-bit Internet address variable.
SNMP_SYNTAX_CNTR32 | Indicates a counter variable that increases until it reaches a maximum value of (2^32) – 1.
SNMP_SYNTAX_GAUGE32 | Indicates a gauge variable that is a non-negative integer that can increase or decrease, but never exceed a maximum value.
SNMP_SYNTAX_TIMETICKS | Indicates a counter variable that measures the time in hundredths of a second, until it reaches a maximum value of (2^32) – 1. It is a non-negative integer that is relative to a specific timer event.
SNMP_SYNTAX_OPAQUE | This type provides backward compatibility, and should not be used for new object types. It supports the capability to pass arbitrary Abstract Syntax Notation One (ASN.1) syntax.
SNMP_SYNTAX_CNTR64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
SNMP_SYNTAX_UINT32 | Indicates a 32-bit unsigned integer variable.
SNMP_SYNTAX_NOSUCHOBJECT | Indicates that the agent does not support the object type that corresponds to the variable.
SNMP_SYNTAX_NOSUCHINSTANCE | Indicates that the object instance does not exist for the operation.
SNMP_SYNTAX_ENDOFMIBVIEW | Indicates the WinSNMP application is attempting to reference an object identifier that is beyond the end of the MIB tree that the agent supports.

The last three syntax types describe exception conditions under the SNMP version 2C(SNMPv2C) framework.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpGetVb function returns the variable name of the variable binding entry in the structure pointed to by the name parameter. It returns the variable's associated value in the structure pointed to by the value parameter.

On input, the SnmpGetVb function ignores the members of the smiOID and smiVALUE structures pointed to by the name and value parameters respectively. The Microsoft WinSNMP implementation overwrites the members if the function completes successfully.

Valid values for a WinSNMP application to use for the index parameter are as follows:

  • The return value from a call to the SnmpCountVbl function
  • The error index field of an SNMP_PDU_RESPONSE protocol data unit (PDU) returned by a call to the SnmpRecvMsg function

The WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure pointed to by the name parameter. The application must also call the SnmpFreeDescriptor function to release resources allocated for the smiVALUE structure pointed to by the value parameter under the conditions following. If the value member is an smiOCTETS or an smiOID structure, the application must call SnmpFreeDescriptor to free the resources allocated for these structures. For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCountVbl, SnmpRecvMsg, SnmpFreeDescriptor, smiOID, smiVALUE, smiOCTETS


SnmpGetVendorInfo

A WinSNMP application calls the SnmpGetVendorInfo function to retrieve information about the Microsoft WinSNMP implementation. The function returns the information in an smiVENDORINFO structure. The SnmpGetVendorInfo function is an element of the WinSNMP API, version 2.0.

SNMPAPI_STATUS SnmpGetVendorInfo(
  smiLPVENDORINFO vendorInfo  // pointer to structure to receive
                              //   information
);

Parameters

vendorInfo
[out] Pointer to an smiVENDORINFO structure to receive information. The information includes a way to contact Microsoft and the enterprise number assigned to Microsoft by the Internet Assigned Numbers Authority (IANA).

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_NOOP | The vendorInfo parameter is NULL.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, smiVENDORINFO


SnmpListen

The WinSNMP SnmpListen function registers a WinSNMP application as an SNMP agent. An agent application calls this function to inform the Microsoft WinSNMP implementation that an entity will be acting in the role of an SNMP agent. An application also calls this function to inform the implementation when an entity will no longer be acting in this role. The SnmpListen function is an element of the WinSNMP API, version 2.0.

SNMPAPI_STATUS SnmpListen(
  HSNMP_ENTITY hEntity,   // handle to the entity
                          //   that will receive notifications
  SNMPAPI_STATUS lStatus  // flag to indicate agent role
);

Parameters

hEntity
[in] Handle to the WinSNMP entity to notify when the Microsoft WinSNMP implementation receives an incoming SNMP request message (PDU) This parameter identifies the agent application. For more information, see the following Remarks and Return Values sections.

When you call the SnmpCreateSession function, you can specify whether the implementation should use a window notification message or an SNMPAPI_CALLBACK function to notify the application when an SNMP message or asynchronous event is available.

lStatus
[in] Specifies an unsigned long integer variable that indicates whether the WinSNMP entity identified by the hEntity parameter is acting in an SNMP agent role, or if it is no longer acting in this role. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_ON | The specified WinSNMP entity is functioning in an agent role.
SNMPAPI_OFF | The specified WinSNMP entity is not functioning in an agent role.

Passing a value of SNMPAPI_OFF releases both the resources allocated to the entity and the port assigned it. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid. This parameter must be a handle returned by a previous call to the SnmpStrToEntity function.
SNMPAPI_MODE_INVALID | The lStatus parameter is invalid.
SNMPAPI_NOOP | The entity specified by the hEntity parameter is already functioning in the role of an SNMP agent.
SNMPAPI_TL_RESOURCE_ERROR | There is a network transport layer error. A socket could not be created for the entity specified by the hEntity parameter.
SNMPAPI_TL_OTHER | An error occurred in the network transport layer while trying to bind a socket for the entity specified by the hEntity parameter.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

When you specify an entity, you explicitly specify the address family, interface address, and port for the entity. This is because WinSNMP assigns these attributes to each WinSNMP entity as a result of a call to the SnmpStrToEntity function. The implementation uses the address and port settings currently assigned to the entity specified by the hEntity parameter when it sends notifications to the agent application. For more information, see SnmpSetPort.

When you call the SnmpClose function for a WinSNMP session and the SnmpCleanup function for a WinSNMP application, you must release all ports associated with WinSNMP agent applications.

For more information about SNMP management applications and agent applications, see Registering an SNMP Agent Application and About SNMP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpRecvMsg, SnmpSendMsg, SnmpSetPort, SnmpStrToEntity, SnmpClose, SnmpCleanup


SnmpOidCompare

The WinSNMP SnmpOidCompare function lexicographically compares two SNMP object identifiers, up to the length specified by the maxlen parameter.

SNMPAPI_STATUS SnmpOidCompare(
  smiLPCOID xOID,      // first object identifier to compare
  smiLPCOID yOID,      // second object identifier to compare
  smiUINT32 maxlen,    // maximum length to compare
  smiLPINT result      // result of comparison
);

Parameters

xOID
[in] Pointer to the first smiOID object identifier to compare. The length of the object identifier can be zero.
yOID
[in] Pointer to the second smiOID object identifier to compare. The length of the object identifier can be zero.
maxlen
[in] If not equal to zero, specifies the number of subidentifiers to compare. This parameter must be less than MAXOBJIDSIZE: 128 subidentifiers, the maximum number of components in an object identifier. For additional information, see the following Remarks section.
result
[out] Pointer to an integer variable to receive the result of the comparison. The variable can receive one of the following results.
Result | Meaning
Greater than 0 | xOID is greater than yOID
Equal to 0 | xOID equals yOID
Less than 0 | xOID is less than yOID

For additional comparison conditions, see the following Remarks section.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | One or both of the xOID and yOID parameters is invalid.
SNMPAPI_SIZE_INVALID | The maxlen parameter is invalid. The parameter size is greater than MAXOBJIDSIZE.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP application can call the SnmpOidCompare function to determine whether two object identifiers have common prefixes.

If the maxlen parameter is not equal to zero, and not greater than MAXOBJIDSIZE, the value of maxlen sets the upper limit for the number of subidentifiers to compare. The maximum number of subidentifiers that the SnmpOidCompare function compares defaults to whichever is the smallest number — the maxlen parameter, or the len member of one of the smiOID structures pointed to by the xOID and yOID parameters.

If the maxlen parameter is equal to zero, the maximum number of subidentifiers that the SnmpOidCompare function compares defaults to the number that is the smaller of the len members of the two smiOID structures.

The value of the result parameter will indicate that xOID equals yOID if the two smiOID structures are lexicographically equal and one of the following occurs:

  • SnmpOidCompare compares a maxlen number of subidentifiers.
  • SnmpOidCompare compares the maximum number of subidentifiers, and the len members of both smiOID structures are equal, but less than the maxlen parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, smiOID


SnmpOidCopy

The WinSNMP SnmpOidCopy function copies an SNMP object identifier, allocating any necessary memory for the copy.

SNMPAPI_STATUS SnmpOidCopy(
  smiLPCOID srcOID,      // source object identifier
  smiLPOID dstOID        // destination object identifier
);

Parameters

srcOID
[in] Pointer to an smiOID structure to copy.
dstOID
[out] Pointer to an smiOID structure to receive a copy of the object identifier specified by the srcOID parameter.

Return Values

If the function succeeds, the return value is the number of subidentifiers in the copied object identifier. This number is also the value of the len member of the smiOID structure pointed to by the dstOID parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | The srcOID parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

On input, the SnmpOidCopy function ignores the members of the smiOID structure pointed to by the dstOID parameter. The Microsoft WinSNMP implementation overwrites the smiOID members if the function completes successfully.

The WinSNMP application must call the SnmpFreeDescriptor function to enable the implementation to free resources allocated for the ptr member of the smiOID structure pointed to by the dstOID parameter. For additional information, see WinSNMP Data Management Concepts and Freeing WinSNMP Descriptors.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOID


SnmpOidToStr

The WinSNMP SnmpOidToStr function converts the internal binary representation of an SNMP object identifier to its dotted numeric string format, for example, to "1.2.3.4.5.6".

SNMPAPI_STATUS SnmpOidToStr(
  smiLPCOID srcOID,  // object identifier to convert
  smiUINT32 size,    // buffer size for string
  LPSTR string       // pointer to buffer for converted string
                     //   object identifier
);

Parameters

srcOID
[in] Pointer to an smiOID structure with an object identifier to convert.
size
[in] Specifies the size, in bytes, of the buffer indicated by the string parameter.
string
[out] Pointer to a buffer to receive the converted string object identifier that specifies the SNMP management entity.

Return Values

If the function succeeds, the return value is the length, in bytes, of the string that the WinSNMP application writes to the string parameter. The return value includes a null-terminating byte. This value may be less than or equal to the value of the size parameter, but it may not be greater.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SIZE_INVALID | The size parameter is invalid. This parameter cannot be equal to zero; it must indicate the size of the buffer pointed to by the string parameter.
SNMPAPI_OID_INVALID | The srcOID parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OUTPUT_TRUNCATED | The output buffer length is insufficient.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

It is recommended that a WinSNMP application specify, with the size parameter, a string buffer of MAXOBJIDSTRSIZE length (1408 bytes). This ensures that the output buffer is large enough to hold the converted string. Because the converted string is usually less than MAXOBJIDSTRSIZE, the WinSNMP application can copy the converted string to a smaller buffer. The application can then reuse or free the memory that it allocated for the initial buffer. For additional information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToOid, smiOID


SnmpOpen

The SnmpOpen function requests the Microsoft WinSNMP implementation to open a session for the WinSNMP application. This WinSNMP function enables the implementation to allocate and initialize memory, resources, data structures, and communications mechanisms. The SnmpOpen function returns a handle to the new WinSNMP session.

Note When developing new WinSNMP applications, it is recommended that you call the SnmpCreateSession function to open a WinSNMP session instead of calling the SnmpOpen function.

HSNMP_SESSION SnmpOpen(
  HWND hWnd,      // handle to the notification window
  UINT wMsg       // window notification message number
);

Parameters

hWnd
[in] Handle to a window of the WinSNMP application to notify when an asynchronous request completes, or when trap notification occurs.
wMsg
[in] Specifies an unsigned integer that identifies the notification message to send to the WinSNMP application window.

Return Values

If the function succeeds, the return value is a handle that identifies the WinSNMP session that the implementation opens for the calling application.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_HWND_INVALID | The hWnd parameter is not a valid window handle.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The SnmpOpen function returns a unique handle to each open WinSNMP session within the calling WinSNMP application. The application must use the session handle that SnmpOpen returns in other WinSNMP function calls to facilitate allocation and deallocation of resources by the implementation. When the implementation allocates resources to an individual session, it performs an orderly release of resources in response to a call to SnmpClose for the session.

The SnmpOpen function passes to the implementation the handle to an application window and a notification message identifier. If the wParam component of the notification message specified by the wMsg parameter is equal to zero, the WinSNMP application must retrieve the incoming protocol data unit (PDU). The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpOpen. If the wParam parameter of the notification message is not equal to zero, it represents a WinSNMP error code. The error code applies to the PDU identified by the request identifier in the lParam parameter of the notification message.

One WinSNMP application can open multiple WinSNMP sessions. If an application opens multiple sessions using the same window handle, it is recommended that the WinSNMP application specify a unique wMsg parameter for each session.

It is recommended that a WinSNMP application call the SnmpClose function once for each session that the implementation opens as a result of a call to the SnmpOpen function. If a WinSNMP application terminates unexpectedly, it must call SnmpCleanup before it terminates to enable the implementation to deallocate all resources. The implementation treats one SnmpCleanup call as if it were a series of SnmpClose calls, one call for each session the implementation opens as a result of a call to SnmpOpen.

For information about opening a WinSNMP session and specifying the method used to inform the session of available SNMP messages and asynchronous events, see SnmpCreateSession. When you call SnmpCreateSession you can specify a window notification message or an SNMPAPI_CALLBACK function to notify the session.

For more information, see WinSNMP Sessions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpClose, SnmpCleanup, SnmpRecvMsg, SNMPAPI_CALLBACK, SnmpCreateSession


SnmpRecvMsg

The WinSNMP SnmpRecvMsg function retrieves the results of a completed asynchronous request submitted by a call to the SnmpSendMsg function, in the form of an SNMP message. The SnmpRecvMsg function also returns outstanding trap data and notifications registered for a WinSNMP session.

SNMPAPI_STATUS SnmpRecvMsg(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  LPHSNMP_ENTITY srcEntity,   // handle to the source entity
  LPHSNMP_ENTITY dstEntity,   // handle to the target entity
  LPHSNMP_CONTEXT context,    // handle to the context
  LPHSNMP_PDU PDU             // handle to the PDU
);

Parameters

session
[in] Handle to the WinSNMP session.
srcEntity
[out] Pointer to a variable that receives a handle to the entity that sends the message. Note that the srcEntity parameter to the SnmpRegister function specifies a handle to the management entity that registers for trap notification.
dstEntity
[out] Pointer to a variable that receives a handle to the entity that receives the message. Note that the dstEntity parameter to the SnmpRegister function specifies a handle to the management entity that sends traps.
context
[out] Pointer to a variable that receives a handle to the context, which is a set of managed object resources. The entity specified by the srcEntity parameter issues the message from this context.
PDU
[out] Pointer to a variable that receives a handle to the protocol data unit (PDU) component of the message.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS, and the output parameters contain the values indicated in the preceding parameter descriptions.

If the function fails, the return value is SNMPAPI_FAILURE. If the function fails with an extended error code that indicates a network transport layer error, that is, one that begins with SNMPAPI_TL_, the output parameters also contain the values indicated preceding to enable the WinSNMP application to recover gracefully.

To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_NOOP | The specified session has no messages in its queue at this time.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_NOT_SUPPORTED | The network transport layer does not support the SNMP protocol.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_TL_RESOURCE_ERROR | A resource error occurred in the network transport layer.
SNMPAPI_TL_UNDELIVERABLE | The entity specified by the dstEntity parameter is unavailable.
SNMPAPI_TL_SRC_INVALID | The entity specified by the srcEntity parameter was not initialized.
SNMPAPI_TL_INVALID_PARAM | A network transport layer function call received an invalid input parameter.
SNMPAPI_TL_PDU_TOO_BIG | The PDU is too large for the network transport layer to send or receive.
SNMPAPI_TL_OTHER | An undefined network transport layer error occurred.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

The SnmpCreateSession function passes an application window handle and notification message identifier to the Microsoft WinSNMP implementation. When the application window receives the notification message specified by the wMsg parameter, the WinSNMP application must call the SnmpRecvMsg function with the session handle returned by SnmpCreateSession to retrieve an incoming protocol data unit (PDU). For additional information, see About SNMP Messages.

The SnmpRecvMsg function instantiates four objects and allocates their resources: two entity handles, a context handle, and a PDU handle. The handle to the variable bindings list component of the returned PDU is not instantiated until the WinSNMP application calls the SnmpGetPduData function. When it no longer needs the resources SnmpRecvMsg returns, the WinSNMP application must free the individual resources using the WinSNMP function that corresponds to the resource. For additional information, see SnmpFreePdu, SnmpFreeEntity, and SnmpFreeContext.

When the implementation receives traps from an entity operating under the SNMP version 1 framework (SNMPv1), it translates the traps to the SNMP version 2C (SNMPv2C) format. Therefore, when SnmpRecvMsg delivers a trap it is always in the SNMPv2C format. For additional information, see Translating Traps from SNMPv1 to SNMPv2C and WinSNMP Programming Tasks.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreePdu, SnmpFreeEntity, SnmpFreeContext, SnmpSendMsg, SnmpRegister, SnmpGetPduData


SnmpRegister

The WinSNMP SnmpRegister function registers or unregisters a WinSNMP application for trap and notification reception. The application can register and receive traps and notifications, or unregister and disable traps and notifications.

A WinSNMP application can register or unregister for one type of trap or notification, or for all traps and notifications, depending on the value of the notification parameter.

SNMPAPI_STATUS SnmpRegister(
  HSNMP_SESSION session,   // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,  // handle to the entity that is
                           //   the source of the request
  HSNMP_ENTITY dstEntity,  // handle to the entity that
                           //   receives the request
  HSNMP_CONTEXT context,   // handle to the context
  smiLPCOID notification,  // trap-matching sequence
  smiUINT32 state          // flag for trap reception
);

Parameters

session
[in] Handle to the WinSNMP session that is registering or unregistering for traps and notifications.
srcEntity
[in] Handle to the management entity that is the source of the registration request. This entity, acting in an SNMP manager role, will receive the trap or notification.

If this parameter is NULL, the Microsoft WinSNMP implementation registers or unregisters all sources of trap and notification requests.

Note that the srcEntity parameter to the SnmpRecvMsg function has a different role. In that function, srcEntity receives a handle to the entity that sent the trap.

dstEntity
[in] Handle to the management entity that is the recipient of the registration request. This entity, acting in an SNMP agent role, will send the trap or notification.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP application for traps and notifications from all management entities.

Note that the dstEntity parameter to the SnmpRecvMsg function receives a handle to the management entity that registers for trap notification.

context
[in] Handle to the context, which is a set of managed object resources.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP application for traps and notifications for every context.

notification
[in] Pointer to an smiOID structure that contains the pattern-matching sequence for one type of trap or notification. The implementation uses this sequence to identify the type of trap or notification for which the WinSNMP application is registering or unregistering. For additional information, see the following Remarks section.

If this parameter is NULL, the implementation registers or unregisters the WinSNMP application for all traps and notifications from the management entity or entities specified by the dstEntity parameter.

state
[in] Specifies an unsigned long integer variable that indicates whether the WinSNMP application is registering to receive traps and notifications, or if it is unregistering. This parameter should be equal to one of the following values, but if it contains a different value, the implementation registers the application.
Value | Meaning
SNMPAPI_OFF | Disable traps and notifications.
SNMPAPI_ON | Register to receive traps and notifications.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_OID_INVALID | The notification parameter is invalid.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_IN_USE | The trap port is not available.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

Typically a WinSNMP manager application, rather than an agent application, calls the SnmpRegister function.

If a WinSNMP application passes NULL in a call to the SnmpRegister function in the srcEntity, dstEntity, context, or notification parameters, the implementation does not use that parameter to filter traps and notifications from reaching the WinSNMP application. If an application passes NULL in all of the parameters mentioned previously, the implementation delivers all received notifications to the session.

If a WinSNMP application registers to receive a specific type of trap or notification, it must define an object identifier, that is, an smiOID structure, that corresponds to that type of trap. The notification parameter must point to this structure. RFC 1907, "Management Information Base for Version 2 of the Simple Network Management Protocol (SNMPv2)," defines trap and notification object identifiers. For additional information, see Managing Traps and Notifications and Translating Traps from SNMPv1 to SNMPv2C.

The implementation uses the value of the notification parameter as a pattern to match against received traps and notifications. For example, if the WinSNMP application passes n number of subidentifiers in the notification parameter, and the first n subidentifiers in a received trap match all the passed subidentifiers, then the trap object identifier is a match. If a received trap has fewer subidentifiers than n, the object identifier does not match. If there is a match, the implementation sends the trap or notification to the WinSNMP application.

If any or all of the dstEntity, srcEntity, or context parameters are NULL, the implementation may need to allocate resources on a subsequent call to the SnmpRecvMsg function, for that function's corresponding parameters. When the WinSNMP application no longer needs the resources SnmpRecvMsg returns, the application must free the individual resources with the function that corresponds to the resource. For additional information, see SnmpFreeEntity and SnmpFreeContext.

For more information, see Multiple Trap Registrations.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCreateSession, SnmpRecvMsg, SnmpFreeEntity, SnmpFreeContext


SnmpSendMsg

A WinSNMP application calls the SnmpSendMsg function to request that the Microsoft WinSNMP implementation transmit an SNMP protocol data unit (PDU), in the form of an SNMP message. The WinSNMP application specifies a source entity, a destination entity, and a context for the request.

If a WinSNMP application expects a PDU in response to a SnmpSendMsg request, it must retrieve the PDU. To do this, the application must call the SnmpRecvMsg function using the session handle returned by SnmpCreateSession.

SNMPAPI_STATUS SnmpSendMsg(
  HSNMP_SESSION session,      // handle to the WinSNMP session
  HSNMP_ENTITY srcEntity,     // handle to the source entity
  HSNMP_ENTITY dstEntity,     // handle to the target entity
  HSNMP_CONTEXT context,      // handle to the context
  HSNMP_PDU PDU               // handle to the PDU
);

Parameters

session
[in] Handle to the WinSNMP session.
srcEntity
[in] Handle to the management entity that initiates the request to send the SNMP message.
dstEntity
[in] Handle to the target entity that will respond to the SNMP request.
context
[in] Handle to the context, (a set of managed object resources), that the target management entity controls.
PDU
[in] Handle to the protocol data unit that contains the SNMP operation request.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function may return one of the following WinSNMP or network transport layer errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_INVALID | One or both of the entity parameters is invalid.
SNMPAPI_CONTEXT_INVALID | The context parameter is invalid.
SNMPAPI_PDU_INVALID | The PDU parameter is invalid.
SNMPAPI_OPERATION_INVALID | The operation specified in the PDU_type field of the PDU is inappropriate for the destination entity. For more information, see the following Remarks section.
SNMPAPI_TL_NOT_INITIALIZED | The network transport layer was not initialized.
SNMPAPI_TL_NOT_SUPPORTED | The network transport layer does not support the SNMP protocol.
SNMPAPI_TL_NOT_AVAILABLE | The network subsystem failed.
SNMPAPI_TL_RESOURCE_ERROR | A resource error occurred in the network transport layer.
SNMPAPI_TL_SRC_INVALID | The entity specified by the srcEntity parameter was not initialized.
SNMPAPI_TL_INVALID_PARAM | A network transport layer function call received an invalid input parameter.
SNMPAPI_TL_PDU_TOO_BIG | The PDU is too large for the network transport layer to send or receive.
SNMPAPI_TL_OTHER | An undefined network transport layer error occurred.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

For additional information, see Network Transport Errors.

Remarks

The SnmpSendMsg function executes asynchronously and therefore returns immediately.

The implementation notifies the WinSNMP application when the asynchronous request is completed. The implementation does this by sending a notification message to the window specified by the wMsg and hWnd parameters, respectively, in the initial call to SnmpCreateSession for the session. When the application window receives the notification message, the WinSNMP application must retrieve the incoming PDU. The application does this by calling the SnmpRecvMsg function with the session handle returned by SnmpCreateSession.

When a WinSNMP application calls the SnmpSendMsg function, the implementation determines which network transport protocol and SNMP version framework to use to complete the transmission request. The implementation determines this by matching its capabilities with properties associated with the requesting session and with the target management entity. This information is available from values in the implementation's database.

If a WinSNMP application requests functionality that is available under the SNMP version 2C framework (SNMPv2C), but the target entity uses the SNMP version 1 framework (SNMPv1), the implementation attempts to translate the request to SNMPv1. To do this, the implementation uses the procedures defined in RFC1908, "Coexistence between Version 1 and Version 2 of the Internet-standard Network Management Framework." If translation is not possible, SnmpSendMsg fails with the extended error code SNMPAPI_OPERATION_INVALID. This situation occurs, for example, when an application attempts to send a PDU with the SNMP_PDU_InformRequest data type to an SNMPv1 destination entity.

For additional information, see WinSNMP Programming Tasks and About SNMP Messages.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCreateSession, SnmpRecvMsg


SnmpSetPduData

The WinSNMP SnmpSetPduData function updates selected data fields in the specified SNMP protocol data unit (PDU).

SNMPAPI_STATUS SnmpSetPduData(
  HSNMP_PDU PDU,                 // handle to the PDU
  const smiINT *PDU_type,        // pointer to the PDU type
  const smiINT32 *request_id,    // pointer to the PDU request identifier
  const smiINT *non_repeaters,   // valid only for an
                                 //   SNMP_PDU_GETBULK request
  const smiINT *max_repetitions, // valid only for an
                                 //   SNMP_PDU_GETBULK request
  const HSNMP_VBL *varbindlist   // handle to variable bindings list
);

Parameters

PDU
[in] Handle to an SNMP PDU.
PDU_type
[in] Pointer to a variable with a value to update the PDU_type field of the specified PDU. This parameter can also be NULL.
request_id
[in] Pointer to a variable with a value to update the request_id field of the specified PDU. This parameter can also be NULL.
non_repeaters
[in] If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter points to a variable with a value to update the non_repeaters field of the specified PDU. The Microsoft WinSNMP implementation ignores this parameter for other PDU types. This parameter can also be NULL.
max_repetitions
[in] If the PDU_type parameter is equal to SNMP_PDU_GETBULK, this parameter points to a variable with a value to update the max_repetitions field of the specified PDU. The implementation ignores this parameter for other PDU types. This parameter can also be NULL.
varbindlist
[in] Pointer to a variable with a value that updates the handle to the variable bindings list field of the specified PDU. This parameter can also be NULL.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_PDU_INVALID | The PDU type is invalid.
SNMPAPI_VBL_INVALID | The variable bindings list is invalid.
SNMPAPI_NOOP | All input parameters are NULL. The SNMP operation was not performed.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

All parameters of the SnmpSetPduData function are required. However, all parameters, except the PDU parameter, can be NULL. If the WinSNMP application passes NULL in a parameter, SnmpSetPduData does not update the corresponding field in the PDU. Because SnmpSetPduData passes parameters as pointers to values, an application can still update a PDU field with NULL.

The value of one PDU field can be valid alone, but may be invalidated in combination with values for other fields. The implementation validates the PDU and the other message elements when the application calls the SnmpSendMsg or the SnmpEncodeMsg functions. The implementation rejects invalid PDUs.

The only type of trap PDU you can update with a call to the SnmpSetPduData function is an SNMPv2C trap PDU.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSendMsg, SnmpEncodeMsg


SnmpSetPort

A WinSNMP application calls the SnmpSetPort function to change the port assigned to a destination entity. The SnmpSetPort function is an element of the WinSNMP API, version 2.0.

SNMPAPI_STATUS SnmpSetPort(
  HSNMP_ENTITY hEntity,  // handle to the destination entity
  UINT nPort             // new port assignment
);

Parameters

hEntity
[in] Handle to a WinSNMP destination entity. This parameter can specify the handle to an entity acting in the role of an SNMP agent application as a result of a call to the SnmpListen function. For more information, see the following Remarks section.
nPort
[in] Specifies an unsigned integer that identifies the new port assignment for the destination entity. If you specify a local address that is busy, or if you specify a remote address that is unavailable, a call to the SnmpSetPort function fails.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_OPERATION_INVALID | The entity specified by the hEntity parameter is already functioning in an agent role as the result of a call to the SnmpListen function. For more information, see the following Remarks section.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid. This parameter must be a handle returned by a previous call to the SnmpStrToEntity function.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The Microsoft WinSNMP implementation assigns a port to each management entity as a result of a WinSNMP application's call to the SnmpStrToEntity function. If the SNMPAPI_UNTRANSLATED mode is in effect when the implementation creates an entity, the implementation typically assigns the standard SNMP request port for the respective protocol family to the entity; for example, UDP 161 or IPX 36879. If the SNMPAPI_TRANSLATED mode is in effect, the implementation assigns the port specified for the entity in the WinSNMP database. To retrieve the current entity and context translation mode in effect for the implementation, an application can call the SnmpGetTranslateMode function. For more information, see Setting the Entity and Context Translation Mode and The WinSNMP Database.

A call to the SnmpSetPort function fails if the entity specified by the hEntity parameter is currently functioning in an agent role. This is because the entity has already been assigned to a port other than the one specified by the nPort parameter. To ensure assignment of an agent application to a specific port, a WinSNMP application can perform the steps outlined in the following code sample.

hAgent = SnmpStrToEntity (hSession, <addrString>);
lStatus = SnmpSetPort (hAgent, <nPort>);
lStatus = SnmpListen (hAgent, SNMPAPI_ON);

where <addrString> contains the string representation of an IP address or an IPX address, and <nPort> contains the new port assignment for the agent application.

Note that an IPX address contains a network number that consists of eight hexadecimal digits (zero-filled if necessary); a separator (either ":", "." or " – "); and a node number that consists of 12 hexadecimal digits (zero-filled if necessary). For example, 00000001:00081A0D01C2. For more information, see Support for IPX Address Strings in WinSNMP.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpListen, SnmpStrToEntity, SnmpSetPort, SnmpGetTranslateMode


SnmpSetRetransmitMode

The WinSNMP SnmpSetRetransmitMode function enables a WinSNMP application to set the retransmission mode. The Microsoft WinSNMP implementation uses the new retransmission mode to govern transmission time-outs and retransmission attempts on subsequent calls to the SnmpSendMsg function.

SNMPAPI_STATUS SnmpSetRetransmitMode(
  smiUINT32 nRetransmitMode  // new retransmission mode
);

Parameters

nRetransmitMode
[in] Specifies a value for the new retransmission mode. This parameter must be one of the following values.
Value | Meaning
SNMPAPI_ON | The implementation executes the WinSNMP application's retransmission policy.
SNMPAPI_OFF | The implementation does not execute the WinSNMP application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_MODE_INVALID | The implementation does not support the requested retransmission mode.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP manager application, rather than an agent application, calls the SnmpSetRetransmitMode function.

If a WinSNMP application sets the retransmission mode to SNMPAPI_OFF, the implementation does not initiate retransmission attempts for new SNMP communications operations. The new setting affects all subsequent calls to the SnmpSendMsg function, until the WinSNMP application sets the retransmission mode back to SNMPAPI_ON.

Calling the SnmpCancelMsg function is equivalent to calling the SnmpSetRetransmitMode function, for a specific SNMP message, with the retransmission mode equal to SNMPAPI_OFF.

Note If the implementation returns the error SNMPAPI_MODE_INVALID to a call to SnmpSetRetransmitMode, the WinSNMP application must execute the retransmission policy.

For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSendMsg, SnmpRegister, SnmpGetRetransmitMode, SnmpGetTimeout, SnmpGetRetry, SnmpCancelMsg


SnmpSetRetry

The WinSNMP SnmpSetRetry function enables a WinSNMP application to change the retry count value for the retransmission of SNMP message requests. The retry count applies to calls that a WinSNMP application makes to the SnmpSendMsg function for a specified management entity. The Microsoft WinSNMP implementation stores the value in a database.

SNMPAPI_STATUS SnmpSetRetry(
  HSNMP_ENTITY hEntity,    // destination management entity
  smiUINT32 nPolicyRetry   // new retry count value for database
);

Parameters

hEntity
[in] Handle to the destination management entity of interest.
nPolicyRetry
[in] Specifies a new value for the retry count for the management entity. This value replaces the value currently stored in the implementation's database.

If this parameter is equal to zero, and the current retransmission mode is equal to SNMPAPI_ON, the implementation selects a value for the retry count. The implementation uses this value when it executes the WinSNMP application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP manager application, rather than an agent application, calls the SnmpSetRetry function.

For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSetRetransmitMode, SnmpGetRetry, SnmpGetRetransmitMode


SnmpSetTimeout

The WinSNMP SnmpSetTimeout function enables a WinSNMP application to change the time-out value for the transmission of SNMP message requests. The time-out value applies to calls that a WinSNMP application makes to the SnmpSendMsg function for a specified management entity. The Microsoft WinSNMP implementation stores the value in a database.

SNMPAPI_STATUS SnmpSetTimeout(
  HSNMP_ENTITY hEntity,        // destination management entity
  smiTIMETICKS nPolicyTimeout  // new time-out value for database
);

Parameters

hEntity
[in] Handle to the destination management entity of interest.
nPolicyTimeout
[in] Specifies a new time-out value, in hundredths of a second, for the management entity. This value replaces the value currently stored in the implementation's database.

If this parameter is equal to zero, and the current retransmission mode is equal to SNMPAPI_ON, the implementation selects a time-out value. The implementation uses this time-out value when it executes the WinSNMP application's retransmission policy.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_ENTITY_INVALID | The hEntity parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Typically a WinSNMP manager application, rather than an agent application, calls the SnmpSetTimeout function.

For additional information, see About Retransmission and Managing the Retransmission Policy.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpGetTimeout, SnmpSetRetransmitMode, SnmpGetRetransmitMode


SnmpSetTranslateMode

The WinSNMP SnmpSetTranslateMode function enables a WinSNMP application to change the entity and context translation mode. The entity and context translation mode affects the interpretation and return of WinSNMP input and output string parameters.

SNMPAPI_STATUS SnmpSetTranslateMode(
  smiUINT32 nTranslateMode  // new entity/context translation mode
);

Parameters

nTranslateMode
[in] Specifies a value for the new entity and context translation mode. This parameter must be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The Microsoft WinSNMP implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of zero in the version field.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of 1 in the version field.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_MODE_INVALID | The implementation does not support the requested translation mode.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The new entity and context translation mode affects subsequent calls to the SnmpStrToEntity, SnmpStrToContext, SnmpContextToStr, and SnmpEntityToStr functions. The WinSNMP application can change the entity and context translation mode again by making another call to SnmpSetTranslateMode with a different nTranslateMode value.

For additional information, see Setting the Entity and Context Translation Mode.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToContext, SnmpStrToEntity, SnmpContextToStr, SnmpEntityToStr, SnmpGetTranslateMode


SnmpSetVb

The WinSNMP SnmpSetVb function changes variable binding entries in a variable bindings list. This function also appends new variable binding entries to an existing variable bindings list.

SNMPAPI_STATUS SnmpSetVb(
  HSNMP_VBL vbl,     // handle to the variable bindings list
  smiUINT32 index,   // position of the variable binding entry
                     //   in the list
  smiLPCOID name,    // pointer to the variable name portion
                     //   of the entry
  smiLPCVALUE value  // pointer to the variable value portion
                     //   of the entry
);

Parameters

vbl
[in] Handle to the variable bindings list to update.
index
[in] Specifies an unsigned long integer variable that contains the position of the variable binding entry, within the variable bindings list, if this is an update operation. If this is an append operation, this parameter must be equal to zero. For more information, see the following Remarks section.
name
[in] Pointer to an smiOID structure that represents the name of the variable to append or change. For more information, see the following Remarks section.
value
[in] Pointer to an smiVALUE structure. The structure contains the value associated with the variable specified by the name parameter.

Return Values

If the function succeeds, the return value is the position of the updated or appended variable binding entry in the variable bindings list. For additional information, see the following Remarks section.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_VBL_INVALID | The vbl parameter is invalid.
SNMPAPI_INDEX_INVALID | The index parameter is invalid.
SNMPAPI_OID_INVALID | The name parameter is invalid.
SNMPAPI_SYNTAX_INVALID | The syntax member of the structure pointed to by the value parameter is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

Valid values for the index parameter range from zero to n. The value zero indicates an append operation. The value n is the total number of variable binding entries in the variable bindings list. A WinSNMP application should call the SnmpCountVbl function before it calls SnmpSetVb to obtain the total number of variable binding entries.

If the function successfully performs an update operation, the return value equals the value of the index parameter. If the function appends a variable binding entry, the return value is n + 1.

If the name parameter is not NULL, but the value parameter is NULL, the Microsoft WinSNMP implementation initializes the new variable binding entry with the value member set to NULL and with the syntax member set to SNMP_SYNTAX_NULL.

If the index parameter is not equal to zero, and the name parameter is NULL, the Microsoft WinSNMP implementation updates only the value of the variable pointed to by the index parameter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpCountVbl, smiOID, smiVALUE


SnmpStartup

The SnmpStartup function notifies the Microsoft WinSNMP implementation that the WinSNMP application requires the implementation's services. The WinSNMP SnmpStartup function enables the implementation to initialize and to return to the application the version of the Windows SNMP Application Programming Interface (WinSNMP API), the level of SNMP communications that the implementation supports, and the implementation's default translation and retransmission modes.

Note A WinSNMP application must call the SnmpStartup function successfully before it calls any other WinSNMP function.

SNMPAPI_STATUS SnmpStartup(
  smiLPUINT32 nMajorVersion,   // major version number of the WinSNMP API
  smiLPUINT32 nMinorVersion,   // minor version number of the WinSNMP API
  smiLPUINT32 nLevel,          // level of SNMP the implementation supports
  smiLPUINT32 nTranslateMode,  // default entity/context translation mode
  smiLPUINT32 nRetransmitMode  // default retransmission mode
);

Parameters

nMajorVersion
[out] Pointer to an unsigned long integer variable to receive the major version number of the WinSNMP API that the implementation supports. For example, to indicate that the implementation supports WinSNMP version 2.0, the function returns a value of 2.
nMinorVersion
[out] Pointer to an unsigned long integer variable to receive the minor version number of the WinSNMP API that the implementation supports. For example, to indicate that the implementation supports WinSNMP version 2.0, the function returns a value of 0.
nLevel
[out] Pointer to an unsigned long integer variable to receive the highest level of SNMP communications the implementation supports. Upon successful return, this parameter contains a value of 2. For a description of level 2 support, see Levels of SNMP Support.
nTranslateMode
[out] Pointer to an unsigned long integer variable to receive the default translation mode in effect for the implementation. The translation mode applies to the implementation's interpretation of the entity parameter that the WinSNMP application passes to the SnmpStrToEntity function. The translation mode also applies to the string parameter that the WinSNMP application passes to the SnmpStrToContext function. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of zero in the version field.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. For SNMPv2 destination entities, the implementation creates outgoing SNMP messages that contain a value of 1 in the version field.

For additional information, see Setting the Entity and Context Translation Mode.

nRetransmitMode
[out] Pointer to an unsigned long integer variable to receive the default retransmission mode in effect for the implementation. This parameter can be one of the following values.
Value | Meaning
SNMPAPI_OFF | The implementation is not executing the retransmission policy of the WinSNMP application.
SNMPAPI_ON | The implementation is executing the retransmission policy of the WinSNMP application.

For additional information, see About Retransmission.

Return Values

If the function succeeds, the return value is SNMPAPI_SUCCESS, and the parameters contain appropriate values, as indicated in the preceding parameter descriptions.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors. For additional information, see the Remarks section that follows.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

A WinSNMP application must call the SnmpStartup function successfully at least once, before it calls any other WinSNMP function. If a WinSNMP application does call another WinSNMP function, before it successfully calls SnmpStartup, the implementation returns the error SNMPAPI_NOT_INITIALIZED.

The WinSNMP application can call SnmpGetLastError for error information, or retry SnmpStartup if a call to the SnmpStartup function fails. When SnmpStartup returns SNMPAPI_FAILURE, and a subsequent call to SnmpGetLastError returns SNMP_ALLOC_ERROR, the WinSNMP application can elect to wait. It can retry the call to SnmpStartup when the implementation has adequate free resources.

A WinSNMP application can call SnmpStartup multiple times. For example, it may need to retry the function call for the reasons discussed preceding. A WinSNMP application must also call SnmpCleanup at least once, as the last WinSNMP function call before it terminates. Multiple SnmpStartup calls do not require multiple SnmpCleanup calls.

For additional information, see Levels of SNMP Support and About SNMP Versions.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpStrToEntity, SnmpStrToContext, SnmpCleanup


SnmpStrToContext

The WinSNMP SnmpStrToContext function returns a handle to SNMP context information that is specific to the Microsoft WinSNMP implementation. The handle is a valid value that a WinSNMP application can use as the context parameter in a call to the SnmpSendMsg and SnmpRegister functions.

HSNMP_CONTEXT SnmpStrToContext(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  smiLPCOCTETS string     // pointer to a string structure
);

Parameters

session
[in] Handle to the WinSNMP session.
string
[in] Pointer to an smiOCTETS structure that contains a string to interpret. The string can identify a collection of managed objects, or it can be a community string.

The current setting of the entity and context translation mode determines the way SnmpStrToContext interprets the input string structure as shown in the following table.
Entity/Context Translation Mode | Meaning
SNMPAPI_TRANSLATED | The implementation interprets the string parameter as a user-friendly name for a collection of managed objects. The implementation translates the name into its SNMPv1 or SNMPv2C components using the implementation's database.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets the string parameter as a literal SNMP community string.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets the string parameter as a literal SNMP community string.

Return Values

If the function succeeds, the return value is a handle to the context of interest.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_CONTEXT_INVALID | The string parameter format is invalid. For example, the len member or the ptr member of the smiOCTETS structure pointed to by the string parameter is NULL.
SNMPAPI_CONTEXT_UNKNOWN | The value referenced in the string parameter does not exist.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the manner in which SnmpStrToContext interprets the input string structure. For additional information, see Setting the Entity and Context Translation Mode.

The WinSNMP application must call the SnmpFreeContext function to release the context handle allocated by the SnmpStrToContext function. For additional information about releasing resources, see WinSNMP Data Management Concepts.

The WinSNMP application should free the memory associated with the ptr member of the smiOCTETS structure pointed to by the string parameter. This is because the application defines and allocates the resources. For example, if the application allocated resources with a call to the GlobalAlloc function, it should use the GlobalFree function to deallocate the resources. For additional information, see Freeing WinSNMP Descriptors.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpSendMsg, SnmpRegister, SnmpFreeDescriptor, SnmpFreeContext, smiOCTETS


SnmpStrToEntity

The WinSNMP SnmpStrToEntity function returns a handle to information about an SNMP management entity that is specific to the Microsoft WinSNMP implementation.

HSNMP_ENTITY SnmpStrToEntity(
  HSNMP_SESSION session,  // handle to the WinSNMP session
  LPCSTR string           // pointer to a string that identifies
                          //   the entity
);

Parameters

session
[in] Handle to the WinSNMP session.
string
[in] Pointer to a null-terminated string that identifies the SNMP management entity of interest. The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string as follows.
Entity/Context Translation Mode | Meaning
SNMPAPI_TRANSLATED | The implementation interprets the string parameter as a user-friendly name. The implementation translates the name into its SNMPv1 or SNMPv2C components using the implementation's database.
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets the string parameter as a literal SNMP transport address.
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets the string parameter as a literal SNMP transport address.

Return Values

If the function succeeds, the return value is a handle to the SNMP management entity of interest.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_SESSION_INVALID | The session parameter is invalid.
SNMPAPI_ENTITY_UNKNOWN | The entity string is invalid.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The current setting of the entity and context translation mode determines the manner in which SnmpStrToEntity interprets the input string that identifies the management entity of interest. For additional information, see Support for IPX Address Strings in WinSNMP and Setting the Entity and Context Translation Mode.

The WinSNMP application should call the SnmpFreeEntity function to release the entity handle allocated by the SnmpStrToEntity function. For additional information, see WinSNMP Data Management Concepts.

The SnmpStrToEntity function returns a valid entity handle that a WinSNMP application can use as the srcEntity or the dstEntity parameter in multiple WinSNMP functions. These functions include the SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, and SnmpDecodeMsg functions.

The implementation returns the current entity and context translation mode in the nTranslateMode parameter of the SnmpStartup function. A WinSNMP application can change the setting of the entity and context translation mode with a call to the SnmpSetTranslateMode function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeEntity, SnmpSetTranslateMode, SnmpStartup, SnmpSendMsg, SnmpRecvMsg, SnmpRegister, SnmpEncodeMsg, SnmpDecodeMsg


SnmpStrToOid

The WinSNMP SnmpStrToOid function converts the dotted numeric string format of an SNMP object identifier, for example, "1.2.3.4.5.6", to its internal binary representation.

SNMPAPI_STATUS SnmpStrToOid(
  LPCSTR string,      // string object identifier to convert
  smiLPOID dstOID     // object identifier internal representation
);

Parameters

string
[in] Pointer to a null-terminated object identifier string to convert.
dstOID
[out] Pointer to an smiOID structure that receives the converted value.

Return Values

If the function succeeds, the return value is the number of subidentifiers in the converted object identifier. This number is also the value of the len member of the smiOID structure pointed to by the dstOID parameter.

If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.

Error code | Description
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully.
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation.
SNMPAPI_OID_INVALID | The string parameter is invalid. For additional information, see the following Remarks section.
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred.

Remarks

The WinSNMP application must call the SnmpFreeDescriptor function to free resources allocated for the ptr member of the smiOID structure pointed to by the dstOID parameter. On input, SnmpFreeDescriptor ignores the members of this smiOID structure. The Microsoft WinSNMP implementation overwrites the smiOID members if the function completes successfully.

The SnmpStrToOid function fails and returns the SNMPAPI_OID_INVALID error code if the string parameter meets one of the following conditions:

  • Is not null-terminated.
  • Is not the textual form of a valid object identifier.
  • Is insufficient in length; all object identifiers must have two subidentifiers.
  • Exceeds the MAXOBJIDSTRSIZE of 1408 bytes.

For additional information, see WinSNMP Data Management Concepts and Freeing WinSNMP Descriptors.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.
Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpFreeDescriptor, smiOID


WinSNMP Structures

The WinSNMP API functions use the following structures:

smiCNTR64
smiOCTETS
smiOID
smiVALUE
smiVENDORINFO


smiCNTR64

The WinSNMP smiCNTR64 structure contains a 64-bit unsigned integer value. The structure represents a 64-bit counter.

typedef struct {
    smiUINT32   hipart;    // high-order 32 bits
    smiUINT32   lopart;    // low-order 32 bits
} smiCNTR64, *smiLPCNTR64;

Members

hipart
Specifies the high-order 32 bits of the counter.
lopart
Specifies the low-order 32 bits of the counter.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Structures, SnmpGetVb, smiVALUE


smiOCTETS

The WinSNMP smiOCTETS structure passes context strings to multiple WinSNMP functions. The structure also describes and receives encoded SNMP messages.

The smiOCTETS structure contains a pointer to an SNMP octet string of variable length. The structure can be a member of the smiVALUE structure.

typedef struct {
    smiUINT32   len;    // number of bytes in the octet string
    smiLPBYTE   ptr;    // pointer to an octet string
} smiOCTETS, *smiLPOCTETS;

Members

len
Specifies an unsigned long integer value that indicates the number of bytes in the octet string array pointed to by the ptr member.
ptr
Pointer to a byte array that contains the octet string of interest. A NULL-terminating byte is not required.

Remarks

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS structures. The WinSNMP application should not free memory that the implementation allocates for the ptr member of an smiOCTETS structure. Instead, the application must call the SnmpFreeDescriptor function to free the memory.

Because the WinSNMP application allocates memory for input descriptor objects with variable lengths, it must free that memory. For more information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Structures, SnmpStrToContext, SnmpContextToStr, SnmpEncodeMsg, SnmpDecodeMsg, SnmpFreeDescriptor, smiVALUE


smiOID

The WinSNMP smiOID structure passes object identifiers to multiple WinSNMP functions. The structure also receives the variable name of a variable binding entry in a call to the SnmpGetVb function.

The smiOID structure contains a pointer to a variable length array of a named object's subidentifiers. The structure can be a member of the smiVALUE structure.

typedef struct {
    smiUINT32     len;    // number of array elements
    smiLPUINT32   ptr;    // pointer to an array of subidentifiers
} smiOID, *smiLPOID;

Members

len
Specifies an unsigned long integer value that indicates the number of elements in the array pointed to by the ptr member.
ptr
Pointer to an array of unsigned long integers that represent the object identifier's subidentifiers.

Remarks

In an smiOID structure, the format of the array pointed to by the ptr member is one subidentifier per array element. For example, the string "1.3.6.1" would be an array of four elements {1,3,6,1}.

The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOID structures. The WinSNMP application should not free memory that the implementation allocates for the ptr member of an smiOID structure. Instead, the application must call the SnmpFreeDescriptor function to free the memory.

Because the WinSNMP application allocates memory for input descriptor objects with variable lengths, it must free that memory. For more information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Structures, SnmpGetVb, SnmpStrToOid, SnmpOidToStr, SnmpOidCopy, SnmpOidCompare, SnmpFreeDescriptor, smiVALUE


smiVALUE

The WinSNMP smiVALUE structure describes the value associated with a variable name in a variable binding entry.

The syntax member of the smiVALUE structure contains a WinSNMP data type that indicates the type of data in the value member. The value member of the structure is the union of all possible WinSNMP data types.

typedef struct {                // smiVALUE portion of VarBind
   smiUINT32    syntax;         // Insert SNMP_SYNTAX_<type>
     union {
       smiINT    sNumber;       // SNMP_SYNTAX_INT
                                // SNMP_SYNTAX_INT32
       smiUINT32 uNumber;       // SNMP_SYNTAX_UINT32
                                // SNMP_SYNTAX_CNTR32
                                // SNMP_SYNTAX_GAUGE32
                                // SNMP_SYNTAX_TIMETICKS
       smiCNTR64 hNumber;       // SNMP_SYNTAX_CNTR64
       smiOCTETS string;        // SNMP_SYNTAX_OCTETS
                                // SNMP_SYNTAX_OPAQUE
                                // SNMP_SYNTAX_IPADDR
                                // SNMP_SYNTAX_NSAPADDR
       smiOID    oid;           // SNMP_SYNTAX_OID
       smiBYTE   empty;         // SNMP_SYNTAX_NULL
                                // SNMP_SYNTAX_NOSUCHOBJECT
                                // SNMP_SYNTAX_NOSUCHINSTANCE
                                // SNMP_SYNTAX_ENDOFMIBVIEW
     } value;    // union
} smiVALUE, *smiLPVALUE;

Members

syntax
Specifies an unsigned long integer that indicates the syntax data type of the value member. This member can be only one of the types listed in the following table. For more information, see WinSNMP Data Types and RFC 1902, "Structure of Management Information for Version 2 of the Simple Network Management Protocol (SNMPv2)."
Syntax data type | Meaning
SNMP_SYNTAX_INT | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_OCTETS | Indicates an octet string variable that is binary or textual data.
SNMP_SYNTAX_NULL | Indicates a NULL value.
SNMP_SYNTAX_OID | Indicates an object identifier variable that is an assigned name with a maximum of 128 subidentifiers.
SNMP_SYNTAX_INT32 | Indicates a 32-bit signed integer variable.
SNMP_SYNTAX_IPADDR | Indicates a 32-bit Internet address variable.
SNMP_SYNTAX_CNTR32 | Indicates a counter variable that increases until it reaches a maximum value of (2^32) – 1.
SNMP_SYNTAX_GAUGE32 | Indicates a gauge variable that is a non-negative integer that can increase or decrease, but never exceed a maximum value.
SNMP_SYNTAX_TIMETICKS | Indicates a counter variable that measures the time in hundredths of a second, until it reaches a maximum value of (2^32) – 1. It is a non-negative integer that is relative to a specific timer event.
SNMP_SYNTAX_OPAQUE | This type provides backward compatibility, and should not be used for new object types. It supports the capability to pass arbitrary Abstract Syntax Notation One (ASN.1) syntax.
SNMP_SYNTAX_CNTR64 | Indicates a counter variable that increases until it reaches a maximum value of (2^64) – 1.
SNMP_SYNTAX_UINT32 | Indicates a 32-bit unsigned integer variable.
SNMP_SYNTAX_NOSUCHOBJECT | Indicates that the agent does not support the object type that corresponds to the variable.
SNMP_SYNTAX_NOSUCHINSTANCE | Indicates that the object instance does not exist for the operation.
SNMP_SYNTAX_ENDOFMIBVIEW | Indicates the WinSNMP application is attempting to reference an object identifier that is beyond the end of the MIB tree that the agent supports.

The last three syntax types describe exception conditions under the SNMP version 2C (SNMPv2C) framework.

value
Specifies the union of all possible WinSNMP syntax data types, including the smiOID or smiOCTETS descriptor types.

Remarks

A WinSNMP application must check the syntax member of an smiVALUE structure to correctly dereference the value member. The value member can contain a simple scalar value or a non-scalar value like an smiOCTETS or an smiOID descriptor structure.

If the syntax member indicates that the value member is an smiOCTETS or an smiOID descriptor structure, the WinSNMP application must determine whether to free the resources allocated for the structure. The Microsoft WinSNMP implementation allocates and deallocates memory for all output smiOCTETS and smiOID structures. The application must call the SnmpFreeDescriptor function to free the memory for the ptr member of these structures.

Because the WinSNMP application allocates memory for input descriptors with variable lengths, it must free that memory. For more information, see WinSNMP Data Management Concepts.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Structures, smiOCTETS, smiOID, SnmpGetVb, SnmpCreateVbl, SnmpFreeDescriptor


smiVENDORINFO

The smiVENDORINFO structure contains information about the Microsoft WinSNMP implementation. A WinSNMP application can call the SnmpGetVendorInfo function to retrieve this structure. The smiVENDORINFO structure is an element of the WinSNMP API, version 2.0.

typedef struct {
    CHAR  vendorName[MAXVENDORINFO*2];
    CHAR  vendorContact[MAXVENDORINFO*2];
    CHAR  vendorVersionId[MAXVENDORINFO];
    CHAR  vendorVersionDate[MAXVENDORINFO];
    smiUINT32  vendorEnterprise;
} smiVENDORINFO, FAR *smiLPVENDORINFO;

Members

vendorName
Contains the null-terminated string "Microsoft Corporation". The string is suitable for display to end users.
vendorContact
Specifies a null-terminated character string that indicates how Microsoft can be contacted for WinSNMP-related information. For example, this member can contain a postal address, a telephone number or a fax number, a URL, or an e-mail address such as "snmpinfo@microsoft.com". The string is suitable for display.
vendorVersionId
Specifies a null-terminated character string that identifies the version number of the WinSNMP API the Microsoft WinSNMP implementation is currently supporting. The string is suitable for display.
vendorVersionDate
Specifies a null-terminated character string that indicates the release date of the version of the WinSNMP API the Microsoft WinSNMP implementation is currently supporting. The string is suitable for display.
vendorEnterprise
Contains the value 311, Microsoft's enterprise number (permanent address) assigned by the Internet Assigned Numbers Authority (IANA).

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Winsnmp.h.

See Also

WinSNMP API Overview, WinSNMP Structures, SnmpGetVendorInfo


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.